勝手 Mastodon tootctl リファレンス (移植版)

はじめに

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

Qiitaにて公開されていた記事ですが、都合によりZennへ移行しました。

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

公式ドキュメントがあります。
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 の実体

https://github.com/tootsuite/mastodon/tree/master/lib/mastodon

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

tootctlリファレンス

引数の凡例

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

アカウント系(accounts)

Source: lib/mastodon/accounts_cli.rb

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

未検証

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

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

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

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

アカウントを追加する(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

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

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

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

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

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

ユーザー権限に指定する名称について[v4.0.0～]

ユーザー権限については、管理者の設定画面より任意の名前で権限を細分化して登録できるようになった。
デフォルトでは「Owner」「Admin」「Moderator」の3種類。大文字小文字を区別する。

v4.0.0より前のバージョンは「admin」「moderator」「user」の3種類固定だった。

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

モデレーションメニュー

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

管理メニュー

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

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

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

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

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

Option	Description
--email	ユーザー名の代わりに、メールアドレスを指定する。規定値は指定なし(ユーザー名指定) [v4.1.0rc1～]
--dry-run	チェックのみ行う。規定値はなし [v4.1.0rc1～]

ユーザー名、メールアドレス(オプションを付けて指定)のどちらか片方の指定が必要。

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

未検証

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

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

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

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

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

重複するリモートアカウントをマージする(fix_duplicates) [v3.5.0rc3?～]

未検証

同一のActivityPub actor identifier を用いているアカウントを結合する。

$ RAILS_ENV=production bundle exec bin/tootctl accounts fix_duplicates 

Option	Description
--dry-run	チェックのみ行う。規定値はなし

そのような重複はリモートサーバの管理者のドメイン設定不備によって発生することがある。

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

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

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

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

オプションはない。

USERNAME(決め打ちユーザ名)の指定が必要。

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

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

$ RAILS_ENV=production bundle exec bin/tootctl accounts cull 

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

7日以内に活動が確認されたアカウントは、チェックから除外される。
無効になっている（HTTP 404/410が返された）外部ユーザは、ローカルから削除される。

調査中、何件かエラーが続いたらそのサーバの調査をスキップする。
（タイムアウト、接続エラー、SSLエラー）

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

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

未検証

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

リモートユーザのアイコン、ヘッダー画像などを取得しなおす。

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

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

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

特定のユーザをローカルユーザ全員にフォローさせる(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より、フォローはローカルユーザに対してのみ可能となった。

特定のユーザをローカルユーザ全員にアンフォローさせる(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にフルハンドルを指定する）

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

未検証

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

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

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

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

アカウントを承認する(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のいずれかを付ける必要がある。

ローカルユーザーと接触のない外部ユーザーを削る(prune) [v4.1.0rc1～]

未検証

下記に当てはまるリモートユーザーをデータベースから削る。

• ローカルアカウントからフォローされていない
• ローカルアカウントをフォローしていない
• ローカルに投稿が残っていない
• ローカルにメンションしていない
• ローカルの投稿をお気に入りしていない
• ローカルサーバー側でミュート・ブロックされていない

$ RAILS_ENV=production bundle exec bin/tootctl accounts prune

Option	Description
--concurrency=N (-c)	並列処理する数。規定値はN=5。
--dry-run	実際には実行しない。規定値は指定なし(実行する)

ローカル ユーザーを別のアカウントに移行する(migrate) [v4.1.0rc1～]

未検証

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

Option	Description
--replay	移行先のサーバーが引っ越し(Move)アクティビティを適切に処理できなかった場合に備えて、再度マイグレーションを実行する。規定値は指定なし。
--target	移行先のアカウントを指定する
--force	移行先のアカウントにリダイレクトする。規定値は指定なし。

--replay あるいは --targetのいずれかを付ける必要がある。

アカウントのRSA鍵を更新する(rotate_keys_for_account) [v3.5.0rc?～]

未検証

詳細情報がない。

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

USERNAMEのプライベート(RSA)鍵を再生成し、外部サーバへ伝達するものと思われる。

キャッシュ系(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
--concurrency=N (-c)	並列処理する数。規定値はN=5。[v3.0.0～]
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし [v3.0.0?～]

引数 TYPE は必須。

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

正規メールブロック系(canonical_email_blocks) [v4.0.0rc1?～]

Source: lib/mastodon/canonical_email_blocks_cli.rb

canonical e-mail blocks の操作を行うもの、らしい。未確認。

指定したメールアドレスがブロックされているか確認する (find) [v4.0.0rc1?～]

未検証

$ RAILS_ENV=production bundle exec bin/tootctl canonical_email_blocks find EMAIL

指定したメールアドレスがブロックされているか否かを表示する。

指定したメールアドレスのブロックを解除する (remove) [v4.0.0rc1?～]

未検証

$ RAILS_ENV=production bundle exec bin/tootctl canonical_email_blocks remove EMAIL

指定したメールアドレスがブロックされていたらブロックを解除する。

ドメイン系(domains)

Source: lib/mastodon/domains_cli.rb

外部サーバをパージする(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～]
--dry_run	実際には実行しない。規定値は指定なし
--by-uri	与えられたDOMAINを、WebfingerのドメインではなくActor URIのドメイン部として解釈する。規定値は指定なし[v3.5.0rc～]
--include_subdomains	与えられたDOMAINだけでなく、それのサブドメインもまとめてパージする。動作が遅くなることに注意。規定値は指定なし[v4.2.0rc1～]
--limited_federation_mode	連合許可モードが有効になっている場合、許可リストにないドメインをすべてパージする。規定値は指定なし[v4.2.0rc1～]
--purge_domain_blocks	DOMAINのドメインブロック情報も一緒に削除する。規定値は指定なし[v4.2.0rc1～]
--limited-federation-mode	連合許可モードが有効になっている場合、許可リストにないドメインをすべてパージする。規定値は指定なし[v3.2.0rc1～v4.0.2]

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

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

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

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

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

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

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

Option	Description
--concurrency=N (-c N)	HTTPリクエストのスレッド数。規定値はN=50
--format=FORMAT (-f FORMAT)	出力フォーマットを指定する。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に計上される。

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

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

Source: lib/mastodon/email_domain_blocks_cli.rb

ブロックリストを出力する(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

メールドメインブロックを追加する(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

メールの発信元ドメインが違うがIPが同じ、という場合は --with-dns-recordsを付けると一網打尽することができる。

メールドメインブロックを解除する(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

カスタム絵文字系(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	これを付けると絵文字ピッカーに表示しない。規定値は指定なし(絵文字ピッカーに表示する)
--category=CATEGORY	所属させるカテゴリーを指定する。規定値は指定なし [v3.5.0rc?～]

カスタム絵文字をエクスポートする(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	保存先に同名のファイルがあった場合、上書きする。規定値は指定なし(上書きしない)

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

未検証

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

$ RAILS_ENV=production bundle exec bin/tootctl emoji purge 

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

フィード系(feeds)

Source: lib/mastodon/feeds_cli.rb

Redisに対する操作。

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

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

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

Option	Description
--all	全ユーザに対して実行する。規定値は指定なし
--concurrency=N (-c N)	同時実行数。規定値はN=5
--verbose (-v)	処理の詳細情報を表示する。規定値は指定なし
--dry-run	実際には実行しない。規定値は指定なし(実際に実行する)

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

--allオプションを付けると全ユーザを対象に再構築を行う。
USERNAMEを指定することで、特定ユーザに対して再構築を行う。

ホーム・リストタイムラインのフィードをクリアする (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... 

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

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

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

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～]

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

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

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

オプションはない。

これを実行する場合は、 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

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

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

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

$ RAILS_ENV=production bundle exec bin/tootctl media remove

Option	Description
--days=N (-d N)	N日前までのメディアファイルを消す。規定値はN=7(日)
--prune-profiles	アバターとヘッダー画像だけ消す。規定値は指定なし[v4.2.0rc1～]
--remove-headers	ヘッダー画像だけ消す。規定値は指定なし[v4.2.0rc1～]
--include-follows	prune-profilesもしくはremove-headersと同時に指定する。フォロー関係に関係なく消す。規定値は指定なし[v4.2.0rc1～]
--concurrency=N (-c N)	並列処理する数。規定値はN=5。[v3.0.0～]
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし[v3.0.0?～]
--dry-run	実際には実行しない。規定値は指定なし(実行する)

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

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

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

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

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

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

--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)
$

ローカルストレージを総なめし、どこにも属していないファイルを探し出し、削除する。
オブジェクトストレージの種類によっては使用できない可能性がある。
(v3.5.0rcの時点では、s3``filesystemに対応、fogは非対応)

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

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

未検証

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

$ RAILS_ENV=production bundle exec bin/tootctl media refresh

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

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

v3.0.1から、ローカルにキャッシュされているものは再取得しないようになった。
キャッシュされているものも再取得したい場合は--forceオプションを付加する。

メディアファイルの使用容量を計算する(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
$

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

画像がどの投稿に属しているか調べる (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
$

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

全文検索系(search)

Source: lib/mastodon/search_cli.rb

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

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

未検証

$ RAILS_ENV=production bundle exec bin/tootctl search deploy

Option	Description
--concurrency=N (-c N)	N個のプロセスで並列実行する。値として"auto"が許容されなくなった。規定値はN=2。[v3.2.0～]
--batch-size=N (-b N)	バッチ処理する際のレコード数を指定する。規定値はN=1,000で、N>0である必要がある。[v3.5.0rc1～]
--only (accounts｜tags｜statuses)	指定されたインデックスだけを処理する。スペースで区切ることで複数指定可能。規定値はすべてのインデックス。[v3.2.0～]
--import	データベースからインデックスへインポートする。規定値はtrue。[v4.0.0rc1?～]
--clean	古いドキュメントをインデックスから削除する。規定値はtrue。[v4.0.0rc1?～]

サーバ設定系(settings)

Source: lib/mastodon/settings_cli.rb

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

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

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

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

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

承認制にする(approved) [v4.0.0rc1?～]

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

Option	Description
--require_reason (--require_invite_text)	登録時に「意気込み」の入力を必要とするか否か。規定値は指定なし。[v4.0.0rv1～]

新規登録を不許可とする(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(日)
--batch-size=N (-b N)	添付ファイルを消さない（オブジェクトストレージ使用時に有用）。規定値は N=1,000で、N>0である必要がある [v3.5.0rc1～]
--continue	前回のremoveが不完全だった場合、途中から再開する。 規定値は 指定なし(新規) [v3.5.0rc1?～]
--clean-followed	ローカルユーザにフォローされているアカウントの投稿についても削除対象とする。規定値は 指定なし(対象としない) [v3.1.0～]
--skip_status_remove	投稿を消さず、クリーンアップのみ行う。 規定値は 指定なし(削除する) [v3.5.0rc1?～]
--skip-media-remove	添付ファイルを消さない（オブジェクトストレージ使用時に有用）。規定値は 指定なし(消す) [v3.1.3～]
--compress_database	データベースを圧縮し、統計データを更新する。これは長時間かかるためオフラインで実行することを推奨。 規定値は 指定なし(行わない) [v3.5.0rc1?～]

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

• ローカルユーザーの投稿に対してリプライされたもの
• ローカルユーザーによってお気に入りされたもの
• ローカルユーザーによってブックマークされたもの [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
--dry-run	実際には実行しない。規定値は指定なし(実行する)
--verbose (-v)	処理内容を詳細に表示する。規定値は指定なし

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

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

Base CLI

Source: lib/cli.rb

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

サーバを連合から切り離す(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参照をしてどのくらい残っているのか見るとよいかもしれない。

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

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

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

$ RAILS_ENV=production bundle exec bin/tootctl version

実行例

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

その他のタスク

いまはありません

TODO

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

あとがき

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

改訂履歴

20220328

• v3.5.0rc3で全ファイル確認
• 全体的にリファクタリング
• かなり古い情報(v2.5.x系、v3.0.x系)について削除

20221106

• v4.0.0rc1暫定対応

20230202

• v4.1.0rc1暫定対応

以上