[outdated] 勝手 Mastodon tootctl リファレンス

重要なお知らせ

2022/1/11時点で他サイトへ移行したため、以後、本記事はメンテナンスされません。
経緯についてはこちら、移行後の記事はこちらです。

はじめに

この文書はtootctlのヘルプやコードを読み解き、可能な場合は実際に実行し、その動作等をメモしたものです。

かつてMastodon 保守メモの一部でしたが、あまりにも肥大化したため別記事としました。

各種コマンドの変更点について、極力メジャーリリース時に確認するようにしていますが、古い情報・未検証のもの・不正確な記述が混じっていたりします。ご了承ください。
また、そのような記述を発見した場合は、コメント等で教えて頂けたら大変助かります。

公式ドキュメントがあります。
Using the admin CLI - Mastodon documentation

tootctlとは？

ActivityPub対応の分散SNS「Mastodon」の保守管理を行うCLIプログラム。

Mastodon v2.5.0 より導入された。
それ以前のバージョンではRuby on RailsのRakeタスクとして実装されていた。

基本的な使い方は以下の通り。

$ RAILS_ENV=production bundle exec bin/tootctl [COMMAND] [SUBCOMMAND] [ARGS]

引数としてhelpを与えると、コマンドの簡単なヘルプが表示される。
たとえば、直接helpを呼び出すと、tootctlに含まれるコマンド群を見ることができる。

tootctl_help_出力例(v3.2.0rc1)

$ RAILS_ENV=production bundle exec bin/tootctl help
Commands:
  tootctl accounts SUBCOMMAND ...ARGS             # Manage accounts
  tootctl cache SUBCOMMAND ...ARGS                # Manage cache
  tootctl domains SUBCOMMAND ...ARGS              # Manage account domains
  tootctl email_domain_blocks SUBCOMMAND ...ARGS  # Manage e-mail domain blocks
  tootctl emoji SUBCOMMAND ...ARGS                # Manage custom emoji
  tootctl feeds SUBCOMMAND ...ARGS                # Manage feeds
  tootctl help [COMMAND]                          # Describe available commands or one specific command
  tootctl ip_blocks SUBCOMMAND ...ARGS            # Manage IP blocks
  tootctl maintenance SUBCOMMAND ...ARGS          # Various maintenance utilities
  tootctl media SUBCOMMAND ...ARGS                # Manage media files
  tootctl preview_cards SUBCOMMAND ...ARGS        # Manage preview cards
  tootctl search SUBCOMMAND ...ARGS               # Manage the search engine
  tootctl self-destruct                           # Erase the server from the federation
  tootctl settings SUBCOMMAND ...ARGS             # Manage dynamic settings
  tootctl statuses SUBCOMMAND ...ARGS             # Manage statuses
  tootctl upgrade SUBCOMMAND ...ARGS              # Various version upgrade utilities
  tootctl version                                 # Show version

Docker環境でtootctlを流したい時

下記コマンドを使用する。

$ docker-compose run --rm web bin/tootctl [COMMAND] [SUBCOMMAND] [ARGS]

後述のコマンド群は非Docker環境向けですが、適宜読み替えて使用すること。

tootctl の実体

このあたりにある *_cli.rb が実体

tootctlリファレンス

引数の凡例

Parameter	Description
USERNAME	ローカルのユーザ名。alice, bobなど。
ACCT	リモートのユーザ名。フルハンドルとも呼ばれる。[e-mail]など。

アカウント系(accounts)

Source: lib/mastodon/accounts_cli.rb

アカウントを承認する(approve) [v2.8.0～]

登録が承認制の場合、保留中のアカウントを承認する。

$ RAILS_ENV=production bundle exec bin/tootctl accounts approve [USERNAME]

Option	Description
--number=N (-n N)	N個のアカウントを承認する。 規定値は指定なし
--all	保留中のアカウントをすべて承認する。規定値は指定なし

USERNAME(決め打ちユーザ名)の指定、--number あるいは --allのいずれかを付ける必要がある。

ユーザ情報のバックアップを生成する(backup) [v2.6.1～]

ここで言うバックアップとは、アーカイブのことである。
Web UIの「設定」→「データのエクスポート」→「アーカイブデータのリクエスト」を行うことと同義。

実行すると、バックグラウンドで生成処理が行われる。

$ RAILS_ENV=production bundle exec bin/tootctl accounts backup USERNAME 

アカウントを追加する(create)

$ RAILS_ENV=production bundle exec bin/tootctl accounts create USERNAME --email=EMAIL 

Option	Description
--email=EMAIL	ユーザのメールアドレスを指定する。必須。
--confirmed	はじめからメールアドレスを確認済みにする。規定値は指定なし [v2.6.0rc1～]
--role ROLE	ユーザ権限を指定する。規定値はuser(一般ユーザ)
--reattach	古いアカウントを引き継ぐ(要検証)。規定値は指定なし
--force	指定されたアカウントを誰かが使っていた場合、既存アカウントを削除してからアカウントを作成する(要検証)。規定値は指定なし

下記表は--roleで指定できる権限。
それぞれのできること・できないことについては、管理者とモデレータの権限比較 を参照のこと。

ROLE	Description
admin	管理者。すべてのサーバ管理機能が使用できる。
moderator	モデレーター。一部のサーバ管理機能が使用できる。
user	一般ユーザー（規定値）。サーバ管理機能は使えない。

• ユーザ名とメールアドレスは必須
• パスワードはランダムに生成される(作成後に表示される)
• 確認済みステータスになる
• reattach は、アカウントの切り替え（実質アカウント名の変更）に使用するようだ

実行例

$ RAILS_ENV=production bundle exec bin/tootctl accounts create alice --role=user
OK
New password: 522b276a356bd

Rakeタスクを使う場合 (v2.5.0以前)

$ RAILS_ENV=production bundle exec rails mastodon:add_user

ユーザー名、メールアドレスを聞いてくるので入力する。

存在しないリモートユーザを削除する(cull)

リモートユーザが本当に存在するか実際に問い合わせを行い、存在しなければ削除する。

$ RAILS_ENV=production bundle exec bin/tootctl accounts cull 

Option	Description
--dry-run	存在チェックのみ行い、データのパージは行わない。規定値はなし
--concurrency=N (-c N)	並列処理する数。規定値はN=5。[v3.0.0rc1～]

v3.0.0より、プログレスバーと残り時間予測が表示されるようになった。（それ以前は、.と+での表示だった）

無効になっている（HTTP 404/410が返された）外部ユーザは、ローカルから削除される。

調査中、何件かエラーが続いたらそのサーバの調査をスキップする。

認知している外部ユーザ数にもよるが、かなりの時間がかかる。

Rakeタスクを使う場合 (v2.5.0以前)

$ RAILS_ENV=production bundle exec rails mastodon:maintenance:purge_removed_accounts

オプションとして -- -f あるいは -- --force を与えると、確認メッセージ無しで削除を実行する。

リモートに存在せず(HTTP 404ないし410が返された場合)、
かつパージを明示的に指示した場合、そのアカウントをパージ、つまり 抹消する 。

証明書切れ、DNS名前解決に失敗、HTTP 404/410以外のエラーコードが返されたとき、などはスルーされる。
(メンテナンス作業中であった場合等を考慮した措置だと思われる)

https://github.com/tootsuite/mastodon/blob/master/lib/tasks/mastodon.rake#L717

アカウントを削除する(delete) [v2.6.1～]

サスペンド状態になる。
過去の投稿はすべて削除される。

$ RAILS_ENV=production bundle exec bin/tootctl accounts delete USERNAME

特定のユーザをローカルユーザ全員にフォローさせる(follow)[v2.7.0～]

$ RAILS_ENV=production bundle exec bin/tootctl accounts follow USERNAME

Option	Description
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし
--concurrency=N (-c)	並列処理する数。規定値はN=5。[v3.0.0rc1～]

v3.0.0より、フォローはローカルユーザに対してのみ可能となった。

アカウントを結合する(merge) [v3.3.0rc1～]

未検証

外部サーバの異なるアカウントを1つにマージする（まとめる）。
外部サーバのドメインが変わってしまった場合に有効。

$ RAILS_ENV=production bundle exec bin/tootctl accounts merge FROM_ACCT TO_ACCT

Option	Description
--force	強制的にマージする。規定値は指定なし

デフォルトでは、公開鍵が同一のユーザアカウントでないとマージできない。
（公開鍵が同一であれば、ドメインが変わっただけと考えられる。）

ドメインが変わってからaccount rotate等で公開鍵の更新が行われた場合、公開鍵情報によるアカウントの同一性が担保できないためエラーで止まる。
同一アカウントで間違いないと確証を得ている場合のみ、--forceオプションを付けて実行することで強制的にマージすることができる。

ローカルアカウントの編集を行う(modify) [v2.6.1～]

$ RAILS_ENV=production bundle exec bin/tootctl accounts modify USERNAME

Option	Description
--role (admin｜moderator｜user)	ユーザ権限を指定する。
--email [EMAIL]	ユーザのメールアドレスを指定する。上書きされる。
--confirm	メールアドレスを確認済みにする
--enable	アカウントロックを解除する(使用可能になる)
--disable	アカウントロックを行う(使用不能になる)
--disable_2fa	二段階認証を無効にする [～v3.0.0]
--disable-2fa	二段階認証を無効にする [v3.0.0～]
--approve	アカウントを承認する。(承認制の場合) [v3.0.0～？]
--reset-password	パスワードをリセットする [v3.1.2～]

アカウント名の変更を行う場合は、createで--reattachオプションを使用する。
（新しいアカウントを作って、各種情報の紐づけなおしのようなイメージ）

--reset-password を指定すると、新しいパスワードを自動的に決定し表示する。

管理者とモデレータの権限比較 [v3.1.0]

モデレーションメニュー

操作	備考	管理者	モデレータ
操作履歴	管理・モデレーション画面の操作履歴	✔	✔
通報	通報の確認、コメント、対応	✔	✔
アカウント	アカウント一覧、確認、編集等	✔	✔
招待	招待URLの生成	△(設定による)	△(設定による)
ハッシュタグ	プロフィールのタグをディレクトリに出すかどうか	✔	✔
既知のサーバー	他サーバの一覧、ドメインブロック	✔	×
メールブラックリスト	メールのドメインブロックの追加、削除	✔	×

管理メニュー

操作	備考	管理者	モデレータ
ダッシュボード	稼働状況の概略表示	✔	✔
サイト設定	Mastodonの基本設定	✔	×
お知らせ	お知らせの一覧	✔	✔
お知らせ	お知らせの登録、編集、公開設定	✔	×
カスタム絵文字	カスタム絵文字の一覧	✔	✔
カスタム絵文字	カスタム絵文字の登録(コピー)	✔	×
カスタム絵文字	カスタム絵文字の無効化	✔	✔
カスタム絵文字	カスタム絵文字の削除	✔	×
リレー	連合リレーへの参加	✔	×
バックエンド情報の表示	Sidekiq、PgHeroへのアクセス	✔	×

モデレータ権限でも、ローカルユーザのメールアドレスとか見えちゃうので
信頼のおける人にだけ権限を付与しよう！
※ただし、パスワードは暗号化されて格納されており、管理者でも見えない。パスワード忘れの際はリセットするしかない。

外部サーバのユーザの情報を更新する(refresh)

未検証

$ RAILS_ENV=production bundle exec bin/tootctl accounts refresh ACCT

アイコン、ヘッダー画像などを取得しなおす。

Option	Description
--domain [DOMAIN]	特定のドメインに対して実行する。これを指定しない場合はユーザ名の指定が必要。規定値は指定なし
--all	全リモートユーザに対して実行する。これを指定しない場合はユーザ名の指定が必要。規定値は`指定なし
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし
--dry-run	実際には実行しない。規定値は指定なし(実行する)
--concurrency=N (-c)	並列処理する数。規定値はN=5。[v3.0.0rc1～]

ACCT(決め打ちフルハンドル)を指定するか、--all、--domainのいずれかを指定する必要がある。

--domainあるいは--all オプションを指定した場合、Sidekiqキューに積まれ、並列処理される。

Rakeタスクを使って、全サーバを対象に実行する場合 (v2.5.0以前)

全サーバに対して行う場合は、Rakeタスクが用意されている。
時間がかかる上、エラー落ちすることがあるので注意。

$ RAILS_ENV=production bundle exec rails mastodon:media:redownload_avatars

Railsコンソールから実行する場合

特定のサーバに属するユーザを対象にするなど、スコープをカスタマイズしたい場合は、下記Rails Consoleコードを実行する。
where部分を書き換えたり追加したりすれば、様々な条件で引っ掛けることが可能

Account.where(domain: "nagoyadon.jp").find_each do |account|
	printf("%s@%s\n", account.username, account.domain)
	account.reset_avatar!
	account.reset_header!
	account.save
end; 0

引っ掛けられるカラムは、モデルを見ればだいたい分かるかも
https://github.com/tootsuite/mastodon/blob/master/app/models/account.rb

ユーザのリレーションシップをリセットする(reset-relationships) [v2.8.0～]

未検証

指定したユーザのフォロー・フォロワーをリセットする。

$ RAILS_ENV=production bundle exec bin/tootctl accounts reset-relationships USERNAME

Option	Description
--follows	指定したユーザのフォローをすべて外す。規定値は指定なし
--followers	指定したユーザのフォロワーをすべて外す。規定値は指定なし

--followsあるいは--followersのいずれか、もしくは両方を指定する必要がある。

ユーザのRSA鍵を再生成しブロードキャストする(rotate) [v2.6.1～]

未検証

ユーザのRSA鍵を再生成し、外部のサーバに配信する。
セキュリティメンテナンスに使用する？

$ RAILS_ENV=production bundle exec bin/tootctl accounts rotate [USERNAME]

Option	Description
--all	すべてのユーザを対象とする。規定値は指定なし

USERNAME(決め打ちユーザ名)を指定するか、--allのどちらかを指定する必要がある。

特定のユーザをローカルユーザ全員にアンフォローさせる(unfollow)[v2.7.0～]

$ RAILS_ENV=production bundle exec bin/tootctl accounts unfollow ACCT

Option	Description
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし
--concurrency=N (-c)	並列処理する数。規定値はN=5。[v3.0.0rc1～]

外部サーバのユーザに対してアンフォローを投げることも可能。（その場合はACCTにフルハンドルを指定する）

[廃止] メールアドレスを確認する [～v2.5.0]

v2.6.1以降の情報は、「ローカルアカウントの編集を行う」に集約してあります。

Rakeタスクを使う場合 (v2.5.0以前)

$ RAILS_ENV=production bundle exec rails mastodon:confirm_email USER_EMAIL=[e-mail]

[廃止] 特定のユーザを管理者あるいはモデレータにする、権限を剥奪する [～v2.5.0]

v2.6.1以降の情報は、「ローカルアカウントの編集を行う」に集約してあります。

Rakeタスクを使う場合 (v2.5.0以前)

管理者

$ RAILS_ENV=production bundle exec rails mastodon:make_admin USERNAME=hogehoge

モデレータ

$ RAILS_ENV=production bundle exec rails mastodon:make_mod USERNAME=hogehoge

権限を剥奪（一般ユーザ化）

$ RAILS_ENV=production bundle exec rails mastodon:revoke_staff USERNAME=hogehoge

キャッシュ系(cache)

Source: lib/mastodon/cache_cli.rb

Railsキャッシュをクリアする(clear)[v2.8.1～]

Railsアプリのキャッシュを消去する。オプションはない。

$ RAILS_ENV=production bundle exec bin/tootctl cache clear

内部的には、シンプルにRails.cache.clearをキックしている。

カウンタを再集計する (recount)[v3.0.0rc1～]

未検証

ハードキャッシュされているカウンタを再集計する。

$ RAILS_ENV=production bundle exec bin/tootctl cache recount TYPE

Option	Description
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし [v3.0.0～？]
--concurrency=N (-c)	並列処理する数。規定値はN=5。[v3.0.0～]

引数 TYPE は必須。

TYPE	Description
accounts	アカウント周り(フォロー、被フォロー、投稿数)を集計する。
statuses	投稿周り(リプライ数、ブースト数、お気に入り数)を集計する。

ドメイン系(domains)

Source: lib/mastodon/domains_cli.rb

統計情報を取得する(crawl)[v2.7.0rc3～]

認知しているすべてのサーバに対し、統計情報の問い合わせを行い
観測範囲内の統計情報を生成する

$ RAILS_ENV=production bundle exec bin/tootctl domains crawl [START]

Option	Description
--concurrency=N (-c N)	HTTPリクエストのスレッド数。規定値はN=50
--silent (-s)	進捗のドットを表示しない。規定値は指定なし(表示する)[～v3.0.0]
--format=FORMAT (-f)	出力フォーマットを指定する。json、summary、domainsのいずれかを指定する。規定値はsummary
--exclude-suspended (-x)	ドメインブロックしているサーバを結果に含めない。[v3.0.0～]

引数STARTにサーバのドメインを指定することができる。
STARTが指定されなかった場合、自身のサーバが持っている既知のリモートサーバ一覧をシードとして用いる。

summary出力例(v2.7.0rc3)

$ RAILS_ENV=production bundle exec bin/tootctl domains crawl
..................... (中略) .............................
Visited 11658 domains, 6143 failed (1805s elapsed)
Total servers: 3196
Total registered: 1870253
Total active last week: 167957
Total joined last week: 20305

フォーマットとして json を指定した場合、 検出したすべてのサーバの情報が出力される。
膨大な量になるため、--silentオプションを付けたうえでファイルへリダイレクトするなど適宜工夫されたい。

また、domainsフォーマットを指定した場合、検出したすべてのドメインが一覧で出力される。（それ以外の情報は表示されない）
これも膨大な量のため注意されたい。

内部的には、api/v1/instance、api/v1/instance/peers、api/v1/instance/activityの3つのエンドポイントにアクセスし情報を取得しようとする。
そのうちどれか一つでも失敗(HTTP 200以外のレスポンスが返された)すれば、それはfailedに計上される。

報告される登録者数等は、各サーバからのレスポンスを基にするため、悪意あるサーバが不正な値を返した場合、あり得ない数字になったりする。
また、検出中にサーバダウンしていた場合などはもちろん計上されないため、正確な数字ではない。参考程度にするとよい。

外部サーバをパージする(purge)[v2.6.1～]

確実に閉じた、あるいは復旧の見込みがない外部サーバをパージ（切り離し）する。
そのサーバに属するユーザをすべてサスペンド状態にする。（そのため転送されてきた投稿等はすべて削除される）

$ RAILS_ENV=production bundle exec bin/tootctl domains purge [DOMAIN...]

Option	Description
--concurrency=N (-c N)	Nスレッドで並列処理する。規定値はN=5(スレッド) [v3.0.1～]
--verbose (-v)	処理の詳細情報を表示する。規定値は指定なし [v3.0.1～]
--whitelist-mode	ホワイトリストモードが有効になっている場合、ホワイトリストにないドメインをすべてパージする。規定値は指定なし (v3.2.0rc1より、--limited-federation-modeにリネームされました)[～v3.2.0rc1]
--limited-federation-mode	連合許可モードが有効になっている場合、許可リストにないドメインをすべてパージする。規定値は指定なし[v3.2.0rc1～]

通常モードにおいては、引数 DOMAIN は必須。purgeしたいサーバのドメインを指定する。複数指定も可能。

通常モードから連合許可モード（旧：ホワイトリストモード）に切り替えた場合、あらかじめドメインの許可リストを用意してから --limited-federation-mode オプションを付加して実行する。
それにより、許可リストにないドメインをすべてパージすることができる。
※連合許可モードの設定は、.env.production にて行う。

purgeしたサーバが復活したらどうなるの？

新しく発見したサーバ扱いになる。
そのため、フォロー関係に不整合が発生することがあるので注意。
（自分から見るとフォロワーから外れているのに、相手から見るとフォローされた状態、など）

カスタム絵文字系(emoji)

Source: lib/mastodon/emoji_cli.rb

カスタム絵文字をインポートする(import)[v2.6.1～]

未検証

GZipされたTARアーカイブからカスタム絵文字をインポートする。
ファイルの拡張子は.pngである必要がある。
ショートコードとして、拡張子を除いたファイル名が使われる。

$ RAILS_ENV=production bundle exec bin/tootctl emoji import PATH

引数 PATHは必須。GZipされたTARアーカイブ（.tar.gz等）へのパスを指定する。

Option	Description
--prefix=PREFIX	ショートコードの接頭辞を指定する。規定値は指定なし
--suffix=SUFFIX	ショートコードの接尾辞を指定する。規定値は指定なし
--overwrite	これを付けると、同じショートコードの絵文字があった場合上書きする。規定値は指定なし(上書きしない)
--unlisted	これを付けると絵文字ピッカーに表示しない。規定値は指定なし(絵文字ピッカーに表示する)

(v2.6.1でのヘルプテキストに不備があり、実際はGZipされたTARアーカイブである必要があった)

全てのカスタム絵文字を消す(purge)[v2.8.0～]

未検証

登録されているカスタム絵文字をすべて削除する

$ RAILS_ENV=production bundle exec bin/tootctl emoji purge 

Option	Description
--remote-only	リモートの絵文字のみ対象とする。規定値は指定なし(すべてを対象とする) [v3.1.0～]

カスタム絵文字をエクスポートする(export)[v3.1.4～]

未検証

絵文字を .tar.gz 形式でエクスポートする。

$ RAILS_ENV=production bundle exec bin/tootctl emoji export PATH

引数 PATHは必須。保存先ディレクトリのパスを指定する。
指定したディレクトリに export.tar.gz というファイル名でエクスポートされる。

Option	Description
--category=PREFIX	絵文字のカテゴリーを指定する。規定値は指定なし(すべて対象)
--overwrite	保存先に同名のファイルがあった場合、上書きする。規定値は指定なし(上書きしない)

フィード系(feeds)

Source: lib/mastodon/feeds_cli.rb

Redisに対する操作。

ホーム・リストタイムラインのフィードを再構築する (build)

ユーザのタイムラインが表示されない、壊れてしまったときに。

$ RAILS_ENV=production bundle exec bin/tootctl feeds build [USERNAME]

Option	Description
--all	全ユーザに対して実行する。規定値は指定なし
--background	バックグラウンドで実行する(Sidekiqを用い並列処理されるため高速)。規定値は指定なし [v3.0.0で廃止]
--dry-run	実際には実行しない。規定値は指定なし(実際に実行する)
--verbose (-v)	処理の詳細情報を表示する。規定値は指定なし

--verboseを付加すると、フォアグラウンドで実行され、処理が終わったアカウントIDを列挙する。

Rakeタスクを使う場合 (v2.5.0以前)

$ RAILS_ENV=production bundle exec rails mastodon:feeds:build

ホーム・リストタイムラインのフィードをクリアする (clear)

$ RAILS_ENV=production bundle exec bin/tootctl feeds clear

オプションはない。実行すると全ユーザのフィードが削除される。

IPルール系(ip_blocks)

Source: lib/mastodon/ip_blocks_cli.rb

IPアドレスベースのアクセス制限を設定する。
管理画面上の「IPルール」の操作と同義。

IPルールを追加する(add) [v3.3.0rc1～]

新規IPルールを作成する。

$ RAILS_ENV=production bundle exec bin/tootctl ip_blocks add IP... --severity=SEVERITY

IPアドレスは複数指定可能。IPアドレスの範囲を指定する場合は、CIDR表記で行う。（192.168.11.0/24 など）

Option	Description
--severity=SEVERITY	影響度を指定する。（必須）
--comment=COMMENT (-c COMMENT)	コメントを指定する。(オプション？) 規定値は指定なし
--duration=N (-d N)	ルールを適用する時間（秒）を指定する。（オプション？）規定値はNull
--force (-f)	既存のIPルールを上書きする。（オプション）

Severity	Description
no_access	すべてのリソースへのアクセスをブロックする
sign_up_requires_approval	登録に承認を必要とする

v3.3.0rc1においての注意点

v3.3.0rc1 においては、--commentオプションは、コマンドのhelpではオプション扱いとのことだが、
実は必須になっている（データベース側のNOT NULL制約による）。
おそらくバグなので、将来的にどちらかに寄ると思われる。
→ このPRでオプション扱いとなりました（未記入の場合は空白）。

また、--durationオプションも値を指定しないで登録することができるが、そのままだとデータベース上では有効期限expires_atが空白となってしまう。無期限扱いなのか、あるいは無効となるのか不明。

IPルールを削除する(remove) [v3.3.0rc1～]

既存のIPルールを削除する。

$ RAILS_ENV=production bundle exec bin/tootctl ip_blocks remove IP...

IPアドレスは複数指定可能。

Option	Description
--force (-f)	強制的に削除する。（オプション）

通常、厳格なマッチのみ削除されるが、--forceが与えられた場合、そのIPアドレスをカバーしているルールが削除される。

--forceのあるなしの違い

# たとえば `192.168.11.0/24`がブロックされている状況下においては

$ RAILS_ENV=production bundle exec bin/tootctl ip_blocks remove 192.168.11.100
192.168.11.100 is not yet blocked
Removed 0, skipped 1
# --forceなしの場合、厳格なマッチが適用されるため削除されない


$ RAILS_ENV=production bundle exec bin/tootctl ip_blocks remove 192.168.11.100 --force
Removed 1, skipped 0
# --forceありの場合、そのIPが含まれるレンジがあれば削除する

IPルールをエクスポートする(export) [v3.3.0rc1～]

既存のIPルールをエクスポートする。

$ RAILS_ENV=production bundle exec bin/tootctl ip_blocks export 

Option	Description
--format (-f)	フォーマットを指定する。plainもしくはnginx。規定値はplain

そのまま標準出力に出力されるので、リダイレクトするなどするとよい。

メンテナンスタスク系(maintenance)

Source: lib/mastodon/maintenance_cli.rb

重複データをマージ・削除する(fix-duplicates) [v3.2.2～]

$ RAILS_ENV=production bundle exec bin/tootctl maintenance fix-duplicates

オプションはない。

アカウント、投稿、絵文字などの重複データをマージもしくは削除し、インデックスを再構築する。
glibcモジュールの照合順序が変わったことにより、PostgreSQLのデータが重複して登録されてしまう不具合の対応。

問題の詳細情報 → https://wiki.postgresql.org/wiki/Locale_data_changes

これを実行する場合は、 Mastodonプロセスを全て止めておく必要がある。
また、物理削除を行う可能性があるため、 必ずデータベースのバックアップを取ること！！
また性質上、処理に長時間かかるため注意。

ローカルアカウントの重複が見つかった場合、どちらを残すか手動で指定するダイアログが出るらしい（未確認）。

実行例

$ RAILS_ENV=production bundle exec bin/tootctl maintenance fix-duplicates
This task will take a long time to run and is potentially destructive.
Please make sure to stop Mastodon and have a backup.
Continue? (Y/n) Y
Deduplicating accounts… for local accounts, you will be asked to chose which account to keep unchanged.
Restoring index_accounts_on_username_and_domain_lower…
Deduplicating user records…
Restoring users indexes…
Removing duplicate account domain blocks…
Restoring account domain blocks indexes…

（中略）

Restoring tags indexes…
Deduplicating webauthn_credentials…
Restoring webauthn_credentials indexes…
Finished!
$

メディアファイル系(media)

Source: lib/mastodon/media_cli.rb

添付メディア（画像、音声、動画）についての操作。

画像がどの投稿に属しているか調べる (lookup)[v3.1.0～]

指定された画像がどの投稿に属しているか（添付されているか）調べる。

$ RAILS_ENV=production bundle exec bin/tootctl media lookup URL

引数URLは必須。メディアファイルへのURIを入力する。

実行例(v3.3.0rc1)

$ RAILS_ENV=production bundle exec bin/tootctl media lookup https://mastodon.example.com/system/media_attachments/files/000/441/369/original/226be987787cc2a5.png
https://mastodon.example.com/@neustrashimy/103727512070363739
$

**v3.2.1以前の情報**

v3.2.1以前のバージョンでは、調査対象のURIの指定はコマンドライン引数ではなく、
コマンド実行後、URIの入力を促すプロンプトが表示されるので、そこに入力する必要がある。

実行例(v3.2.1)

$ RAILS_ENV=production bundle exec bin/tootctl media lookup
Please enter a URL to the media to lookup: https://mastodon.example.com/system/media_attachments/files/000/334/271/original/8c6541943a3f8304.png?1573179058
https://mastodon.example.com/@kumasun/103099863276308470
$

外部のメディアファイルを取得する(refresh)[v3.0.0rc1～]

未検証

外部サーバからメディアファイルを再ダウンロードする。

$ RAILS_ENV=production bundle exec bin/tootctl media refresh

必ず、--status --account --domain のいずれかひとつを付け、対象を指定する必要がある。

Option	Description
--status=STATUS_ID	STATUS_IDの投稿のメディアファイルを再取得する。
--account=ACCT	ACCTが投稿したメディアファイルを再取得する。フルハンドルを指定する。
--domain=DOMAIN	DOMAINのサーバのメディアファイルを再取得する。
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし[v3.0.0～？]
--dry-run	実際には実行しない。規定値は指定なし(実行する)
--concurrency=N (-c N)	並列処理する数。規定値はN=5。[v3.0.0～]

v3.0.1から、ローカルにキャッシュされているものは再取得しないようになった。

外部サーバの古いメディアファイルを消す(remove)

デフォルトでは7日以前のメディアファイルを消す

$ RAILS_ENV=production bundle exec bin/tootctl media remove

Option	Description
--days=N	N日前までのメディアファイルを消す。規定値はN=7(日)
--background	削除処理をバックグラウンドで行う(Sidekiqを使用して並列処理を行う)。 [v3.0.0で廃止]
--concurrency=N (-c N)	並列処理する数。規定値はN=5。[v3.0.0～]
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし[v3.0.0～？]
--dry-run	実際には実行しない。規定値は指定なし(実行する)

並列処理数(concurrency)の数を大きくすると、効率よく処理を行える一方で、他処理の実行が遅延したり、ストレージに対し大きな負荷がかかる可能性があるので、注意が必要。
また、オブジェクトストレージを使用している場合は、DoS攻撃と間違われ規制を受ける可能性が捨てきれないので、特に注意されたい。

Rakeタスク (v2.5.0以前)

$ RAILS_ENV=production bundle exec rails mastodon:media:remove_remote

どこからも参照されていないメディアを削除する (remove-orphans)[v3.1.0～]

ストレージをスキャンし、どこからも参照されていないメディアファイル（画像、動画）を削除する。

orphan = 孤児、孤立、身寄りのない

$ RAILS_ENV=production bundle exec bin/tootctl media remove-orphans

Option	Description
--dry-run	実際には実行しない。規定値は指定なし(実行する)
--start-after=N	指定されたIDから処理を開始する。規定値は指定なし(最初から)
--prefix=PREFIX	検索対象を指定する。規定値は指定なし(全てのメディア)。[v3.1.3～]
--fix-permissions	オブジェクトストレージ上のファイルのパーミッションをPaperClipのデフォルトに戻す。規定値は指定なし(修正しない)。[v3.3.0rc1～]

--prefix オプションの引数として指定できるオブジェクトは以下の通り。

PREFIX	Description
accounts	アカウントのアイコン、ヘッダー画像
custom_emojis	カスタム絵文字
media_attachments	添付メディア (v3.1.2までの固定値)
preview_cards	プレビューカード

実行例

$ RAILS_ENV=production bundle exec bin/tootctl media remove-orphans

(中略)

Found and removed orphan: media_attachments/files/000/348/558/small/b394ef581e3aa53e.jpeg                                                                                                              
Found and removed orphan: media_attachments/files/000/348/559/original/59cc8525dd22cd4d.png

(中略)

179348/179348 |=======================================================| Time: 00:05:36
Removed 5152 orphans (approx. 1.04 GB)
$

ローカルストレージを総なめし、どこにも属していないファイルを探し出し、削除する。
オブジェクトストレージの種類によっては使用できない可能性がある。

処理中にエラーが発生して中断されてしまった場合、コンソールに最終処理IDが表示される。
処理を再開する場合は、--start-after オプションにそのIDを渡すことで途中から再開できる。

メディアファイルの使用容量を計算する(usage)[v3.0.1～]

メディアファイル（画像、動画）がどれだけストレージを使用しているか集計して表示する。

$ RAILS_ENV=production bundle exec bin/tootctl media usage

オプションはない。

実行例

$ RAILS_ENV=production bundle exec bin/tootctl media usage
Attachments:    97.4 GB (2.47 MB local)
Custom emoji:   130 MB (10.5 KB local)
Preview cards:  475 MB
Avatars:        1010 MB (119 KB local)
Headers:        1.77 GB (0 Bytes local)
Backups:        0 Bytes
Imports:        0 Bytes
Settings:       0 Bytes
$

オプションはない。
添付ファイル、カスタム絵文字、プレビューカードといったカテゴリごとに表示される。

プレビューカード系(preview_cards)

Source: lib/mastodon/preview_cards_cli.rb

投稿に含まれるリンクのプレビューカードについての操作

古いプレビューカードを削除する(remove)[v3.0.0rc1～]

1つ1つは小さなものだが、塵も積もれば山となる。

$ RAILS_ENV=production bundle exec bin/tootctl preview_cards remove

Option	Description
--days=N	N日前までのプレビューカードを消す。規定値はN=180(日)
--link	リンクタイプのものだけ対象とする。（動画や画像タイプは対象としない）
--concurrency=N (-c N)	並列処理する数。規定値はN=5。[v3.0.0～]
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし[v3.0.0～？]
--dry-run	実際には実行しない。規定値は指定なし(実行する)

v3.0.0rc1での特記事項

このコマンドで消されるものはpreview_cardsの画像のみのため、preview_cardsのimageが消されたURIを再投稿しても画像の再取得はされないと思われます（文字ベースの説明文などは残るはず）。
あるはずのプレビューカードの画像が表示されない場合は、そのあたりを疑ってみるとよいかもしれません。

なお、v3.0.0rc1の次リリースからは、削除から14日経ったものについては画像を再取得するようになるようです。 該当PR

古い情報 (v2.9.2以前)

v2.9.2現在、tootctl にはそのようなコマンドはない。
Railsコンソールより下記コードを実行することにより、古いものを削除することができる。
1つ1つは小さいが、毎日それなりの勢いで蓄積されていくので、いずれは対処せねばならない問題だと感じている。

PreviewCardお掃除

# どれだけの数があるか、また削減できる容量がどれだけかを確認するだけの場合は、コメントつきのまま実行する。

total_num = 0; 0
total_size = 0; 0

# 下記のwhere句を変更すれば、任意の範囲・条件で絞り込むことが可能。
PreviewCard.where("updated_at < ?", 180.days.ago).find_each do |card|

    total_num = total_num + 1
    if card.image_file_size != nil then
        total_size = total_size + card.image_file_size

        # プレビューカードの画像だけ削除する場合は、下の2行のコメントを外して実行する。
        # card.image.destroy!
        # card.save!
    end

    # プレビューカードごと削除する場合は、下の1行のコメントを外して実行する。
    # card.destroy!

end; 0

printf("%d card(s), %d MBytes reduced\n", total_num, total_size/1.megabytes)

*PreviewCardそのものをdestroyした時の挙動

• そのURLに対するプレビューカードが表示されなくなる。
• そのURLが含まれる投稿に対して、FavやブーストなどのアクションをしてもPreviewCardの再取得は行われない。
• 後に同一のURLが新規に投稿されたとき、新たにプレビューカードの取得が行われる。

PreviewCardのimageだけをdestroyした時の挙動

• そのURLに対するプレビューカードは表示されたままになる。 ただし、画像部分に関してはデフォルトの画像が表示される。
• そのURLが含まれる投稿に対して、Favやブーストなどのアクションをしても、画像の再取得は行われない。
• 後に同一のURLが新規に投稿されても、 再度、画像の取得が行われることはない。

懸念事項

• 検索条件としてupdated_atが一定以上古いもの、としているが、同一URLが投稿されたときにupdated_atが更新されているか未確認。つまり、初出は古いが頻出であるURLのPreviewCardがバッサリ消された場合、再度取得しに行くコストがかかる可能性が高くなる。

検証環境(v2.9.2)にて確認した挙動ですが誤りがあるかもしれません。
よっぽど大丈夫だとは思われますが、ほかの場所に影響が出る可能性も否定できないので、ご利用は自己責任で。

無理やりな感じなので、ほかによいやり方があれば教えてください。

全文検索系(search)

Source: lib/mastodon/search_cli.rb

全文検索エンジン（Elasticsearch）に対する操作。同エンジンが導入されていない環境では使用できない。

全文検索のインデックスを(再)生成する(deploy)[v2.8.0rc1～]

未検証

$ RAILS_ENV=production bundle exec bin/tootctl search deploy

Option	Description
--processes=N	N個のプロセスで並列実行する。N=autoが指定された場合、利用可能なCPU数に応じてプロセス数が決定される。規定値はN=2。[v3.0.0～v3.2.0]
--concurrency=N (-c N)	N個のプロセスで並列実行する。値として"auto"が許容されなくなった。規定値はN=2。[v3.2.0～]
--only (accounts｜tags｜statuses)	指定されたインデックスだけを処理する。スペースで区切ることで複数指定可能。規定値はすべてのインデックス。[v3.2.0～]

サーバ設定系(settings)

Source: lib/mastodon/settings_cli.rb

サーバの設定に対する操作。

新規登録を制御する(registrations)

v3.1.1現在、「承認制」への切り替えはサポートしていない。

新規登録を許可する(open)[v2.6.1？～]

$ RAILS_ENV=production bundle exec bin/tootctl settings registrations open

新規登録を不許可とする(close)[v2.6.1？～]

$ RAILS_ENV=production bundle exec bin/tootctl settings registrations close

投稿系(statuses)

Source: lib/mastodon/statuses_cli.rb

投稿に対する操作。

過去の投稿を削除する(remove)[v2.8.0rc1～]

$ RAILS_ENV=production bundle exec bin/tootctl status remove

Option	Description
--days=N	何日前の投稿を対象とするか。規定値は N=90(日)
--clean-followed	ローカルユーザにフォローされているアカウントの投稿についても削除対象とする。規定値は 指定なし(対象としない) [v3.1.0～]
--skip-media-remove	添付ファイルを消さない（オブジェクトストレージ使用時に有用）。規定値は 指定なし(消す) [v3.1.3～]

以下の投稿はデフォルトで削除対象より除外される。

• ローカルユーザーの投稿に対してリプライされたもの
• ローカルユーザーによってお気に入りされたもの
• ローカルユーザーによってブックマークされたもの [v3.1.0～]
• ブーストされたもの
• リプライであるもの
• ピン止めされているもの

実行例

$ RAILS_ENV=production bundle exec bin/tootctl status remove --days=90
Creating temporary database indices...
Beginning removal... This might take a while...
Beginning removal of now-orphaned media attachments to free up disk space...
Done after 338.574609041214s
Removing temporary database indices to restore write performance...
$ 

removeしたけど空きディスク容量が増えないんだけど？

PostgreSQLでは、データ(行)を削除するだけでは、空きディスク容量は増えません。
削除領域を解放（バキューム）し、OSに返す必要があります。

削除領域をOSに返すためには、PostgreSQLのコンソール等で VACUUM FULLを流します。
VACUUM FULLはテーブルにロックをかけてしまうので、実行中のテーブルへアクセスができなくなります。
そのため、サービスを止めた状態で実行する必要があります。

下の記事に少しメモってあります。

PostgreSQLのvacuumについて調べたメモ

もしくは、オンライン(動かし続けたまま)でも最小限のロックでVACUUM FULL相当の領域開放ができるpg_repack拡張を導入し、実行するという手もあります。

下の記事に少し記載があります。

Mastodon 保守メモ - pg_repack する

アップグレード・マイグレーション系(upgrade)

Source: lib/mastodon/upgrade_cli.rb

ストレージスキーマをアップグレードする(storage-schema)[v3.1.4～]

未検証

すべての添付ファイルを走査し、そのストレージスキーマが古い場合は、新しいストレージスキーマにアップグレードする。

$ RAILS_ENV=production bundle exec bin/tootctl upgrade storage-schema

Option	Description
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし
--dry-run	実際には実行しない。規定値は指定なし(実行する)

たとえば、添付ファイルの保存先を途中から変更した場合(たとえばローカル→オブジェクトストレージ)などに実行すると、古い保存ディレクトリから新しいファイルシステムにファイルの移行が行われる。

また、移行先・元がオブジェクトストレージの場合、かなり量のファイル転送が行われるため、多額の料金がかかる可能性があるので注意。

メールドメインブロック系(email_domain_blocks)

Source: lib/mastodon/email_domain_blocks_cli.rb

メールドメインブロックを追加する(add)[v3.2.0rc1～]

新たにメールドメインブロックを追加する。

$ RAILS_ENV=production bundle exec bin/tootctl email_domain_blocks add DOMAIN...

追加するドメインは複数列挙することができる。

Option	Description
--with-dns-records	DNSに問い合わせを行い、紐づけられたA/AAAA/MXレコードをまとめてブロックする。規定値は指定なし

実行例

$ RAILS_ENV=production bundle exec bin/tootctl email_domain_blocks add --with-dns-records example.com
Added 3, skipped 0

ブロックリストを出力する(list)[v3.2.0rc1～]

未検証

現在のメールドメインブロックを一覧表示する

$ RAILS_ENV=production bundle exec bin/tootctl email_domain_blocks list

オプションはない

実行例

$ RAILS_ENV=production bundle exec bin/tootctl email_domain_blocks list
example.com
  mx2.example.com
  mx1.example.com
  198.51.100.45

メールドメインブロックを解除する(remove)[v3.2.0rc1～]

既存のメールドメインブロックを解除する

$ RAILS_ENV=production bundle exec bin/tootctl email_domain_blocks remove DOMAIN...

解除するドメインは複数列挙することができる。

実行例

$ RAILS_ENV=production bundle exec bin/tootctl email_domain_blocks remove example.com
Removed 3, skipped 0, failed 0

Base CLI

Source: lib/cli.rb

サーバ・サービス全体に対する操作。

バージョン情報を表示する(version)[v2.7.0rc3～]

現在実行中のバージョンを表示する。

$ RAILS_ENV=production bundle exec bin/tootctl version

実行例

$ RAILS_ENV=production bundle exec bin/tootctl version
2.7.0rc3

サーバを連合から切り離す(self-destruct)[v2.8.0rc1～]

サーバを連合から切り離し、安全に閉じられるようにする。

$ RAILS_ENV=production bundle exec bin/tootctl self-destruct

接続されているすべてのサーバに対しaccount deleteアクティビティを送信し、ほかのサーバからキャッシュを削除するよう促す。（促すだけなので完全消去される保証はない）
各ユーザのサスペンドフラグを立てるので、おそらくログインはできなくなる。
そのまま使い続けるとフォロー関係等の不一致が発生し、どんな不具合をもたらすか分からない。
これを実行した後で、サーバを削除するか、データベース等を初期化してから再出発する必要がある。

自分が何をしているのか理解した上で実行すること

実行例(v3.4.0)

$ RAILS_ENV=production bundle exec bin/tootctl self-destruct
Type in the domain of the server to confirm: (確認のためドメイン名を入力する)
This operation WILL NOT be reversible. It can also take a long time.
While the data won't be erased locally, the server will be in a BROKEN STATE afterwards.
A running Sidekiq process is required. Do not shut it down until queues clear.
Are you sure you want to proceed? yes
Do NOT interrupt this process...
Queued 7212 items into Sidekiq for 4 accounts
Wait until Sidekiq processes all items, then you can shut everything down and delete the data
$

**ActiveRecord::RecordNotUnique: PG::UniqueViolation: ～ と言われてしまったとき(v3.4.0で確認)**

エラーメッセージそのものは、カラムの一意制約違反で操作できませんよ、という内容である。
ActiveRecord経由では、単純にDELETE/DROPするだけではなく何かしらのデータ更新作業が行われているらしい。

力技で重複していると言われるindexをDROPすることで解決した。

mastodonユーザで実行

$ psql
mastodon> drop index index_canonical_email_blocks_on_canonical_email_hash;
DROP
mastodon> \q

Sidekiqのキューをredis-cliで確認する

未検証

self-destruct を実行すると、Admin権限を持ったユーザもサスペンドの対象となり、Mastodonにログインができなくなる。
そうなると必然的にSidekiqのWebUIも見ることができなくなり、account deleteアクティビティが流れ切ったのか確認する術がなくなってしまう。
Sidekiqはキューの管理にRedisを使用しているので、Redisのコマンドラインツールredis-cliを用いて、進捗を確認することができる。

redis-cliのhelp抜粋

$ redis-cli --help
redis-cli 5.0.9

Usage: redis-cli [OPTIONS] [cmd [arg [arg ...]]]
  -h <hostname>      Server hostname (default: 127.0.0.1).
  -p <port>          Server port (default: 6379).
  -s <socket>        Server socket (overrides hostname and port).
  -a <password>      Password to use when connecting to the server.
                     You can also use the REDISCLI_AUTH environment
                     variable to pass this password more safely
                     (if both are used, this argument takes predecence).
  -u <uri>           Server URI.

redis-cliでのKey参照

# 保持しているすべてのKeyを表示
redis> keys *

# ワイルドカードで絞り込み
redis> keys push:*

おそらくaccount deleteアクティビティはpush:というプレフィックスのキーを用いるはずなので
たまにKey参照をしてどのくらい残っているのか見るとよいかもしれない。

※この情報が正しいのか確証がありません。詳しい方教えてください…

その他のタスク

[廃止] 誰もフォローしていないユーザの購読をパージ [～v2.5.0]

連合タイムラインを整理したい時に。

v2.5.0まで
tootctl(v2.6.1) においては、代替コマンドはない。

$ RAILS_ENV=production bundle exec rails mastodon:push:clear

TODO

• tootctlの各コマンド類について、v3.0.0から全体的に手を加えられているようなので随時チェックする。
• 可能な限りタグリリースに追従する。

あとがき

• 自分用にメモした内容です。必要に応じて読み替えてください。
• 使用は自己責任でお願いします。何か不具合が起こっても責任取れません。
• こうしたほうがいいよ的なアドバイス、誤記や記載漏れ、動作の違い等の指摘を頂けると大変助かります。
• 連絡先： Mastodon1, Mastodon2

以上