はじめに
この文書は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
に含まれるコマンド群を見ることができる。
$ 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 | リモートのユーザ名。フルハンドルとも呼ばれる。alice@example.com など。 |
アカウント系(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が返された)外部ユーザは、ローカルから削除される。
調査中、何件かエラーが続いたらそのサーバの調査をスキップする。
認知している外部ユーザ数にもよるが、かなりの時間がかかる。
オプションとして リモートに存在せず( 証明書切れ、DNS名前解決に失敗、 https://github.com/tootsuite/mastodon/blob/master/lib/tasks/mastodon.rake#L717Rakeタスクを使う場合 (v2.5.0以前)
$ RAILS_ENV=production bundle exec rails mastodon:maintenance:purge_removed_accounts
-- -f
あるいは -- --force
を与えると、確認メッセージ無しで削除を実行する。HTTP 404
ないし410
が返された場合)、
かつパージを明示的に指示した場合、そのアカウントをパージ、つまり 抹消する 。HTTP 404
/410
以外のエラーコードが返されたとき、などはスルーされる。
(メンテナンス作業中であった場合等を考慮した措置だと思われる)
アカウントを削除する(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~] |
--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タスクが用意されている。Rakeタスクを使って、全サーバを対象に実行する場合 (v2.5.0以前)
時間がかかる上、エラー落ちすることがあるので注意。$ RAILS_ENV=production bundle exec rails mastodon:media:redownload_avatars
特定のサーバに属するユーザを対象にするなど、スコープをカスタマイズしたい場合は、下記Rails Consoleコードを実行する。 引っ掛けられるカラムは、モデルを見ればだいたい分かるかもRailsコンソールから実行する場合
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=hoge@example.tld
[廃止] 特定のユーザを管理者あるいはモデレータにする、権限を剥奪する [~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
|
指定なし(表示する) |
|
--format=FORMAT (-f) | 出力フォーマットを指定する。json 、summary 、domains のいずれかを指定する。規定値はsummary
|
--exclude-suspended (-x) | ドメインブロックしているサーバを結果に含めない。[v3.0.0~] |
引数START
にサーバのドメインを指定することができる。
START
が指定されなかった場合、自身のサーバが持っている既知のリモートサーバ一覧をシードとして用いる。
$ 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~] |
指定なし --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 | 全ユーザに対して実行する。規定値は指定なし
|
指定なし |
|
--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アドレスをカバーしているルールが削除される。
# たとえば `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を入力する。
$ 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以前のバージョンでは、調査対象のURIの指定はコマンドライン引数ではなく、v3.2.1以前の情報
コマンド実行後、URIの入力を促すプロンプトが表示されるので、そこに入力する必要がある。$ 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(日)
|
|
|
--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 | 実際には実行しない。規定値は指定なし(実行する)
|
このコマンドで消されるものはpreview_cardsの画像のみのため、preview_cardsのimageが消されたURIを再投稿しても画像の再取得はされないと思われます(文字ベースの説明文などは残るはず)。 なお、v3.0.0rc1の次リリースからは、削除から14日経ったものについては画像を再取得するようになるようです。 該当PRv3.0.0rc1での特記事項
あるはずのプレビューカードの画像が表示されない場合は、そのあたりを疑ってみるとよいかもしれません。
v2.9.2現在、 *PreviewCardそのものをdestroyした時の挙動 PreviewCardのimageだけをdestroyした時の挙動 懸念事項 検証環境(v2.9.2)にて確認した挙動ですが誤りがあるかもしれません。 無理やりな感じなので、ほかによいやり方があれば教えてください。古い情報 (v2.9.2以前)
tootctl
にはそのようなコマンドはない。
Railsコンソールより下記コードを実行することにより、古いものを削除することができる。
1つ1つは小さいが、毎日それなりの勢いで蓄積されていくので、いずれは対処せねばならない問題だと感じている。
# どれだけの数があるか、また削減できる容量がどれだけかを確認するだけの場合は、コメントつきのまま実行する。
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)
updated_at
が一定以上古いもの、としているが、同一URLが投稿されたときにupdated_at
が更新されているか未確認。つまり、初出は古いが頻出であるURLのPreviewCardがバッサリ消された場合、再度取得しに行くコストがかかる可能性が高くなる。
よっぽど大丈夫だとは思われますが、ほかの場所に影響が出る可能性も否定できないので、ご利用は自己責任で。
全文検索系(search)
Source: lib/mastodon/search_cli.rb
全文検索エンジン(Elasticsearch)に対する操作。同エンジンが導入されていない環境では使用できない。
全文検索のインデックスを(再)生成する(deploy)[v2.8.0rc1~]
未検証
$ RAILS_ENV=production bundle exec bin/tootctl search deploy
Option | Description |
---|---|
N 個のプロセスで並列実行する。N=auto が指定された場合、利用可能なCPU数に応じてプロセス数が決定される。規定値はN=2 。 |
|
--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
はテーブルにロックをかけてしまうので、実行中のテーブルへアクセスができなくなります。
そのため、サービスを止めた状態で実行する必要があります。
下の記事に少しメモってあります。
もしくは、オンライン(動かし続けたまま)でも最小限のロックでVACUUM FULL
相当の領域開放ができる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
アクティビティを送信し、ほかのサーバからキャッシュを削除するよう促す。(促すだけなので完全消去される保証はない)
各ユーザのサスペンドフラグを立てるので、おそらくログインはできなくなる。
そのまま使い続けるとフォロー関係等の不一致が発生し、どんな不具合をもたらすか分からない。
これを実行した後で、サーバを削除するか、データベース等を初期化してから再出発する必要がある。
自分が何をしているのか理解した上で実行すること
Sidekiqのキューをredis-cli
で確認する
未検証
self-destruct
を実行すると、Admin権限を持ったユーザもサスペンドの対象となり、Mastodonにログインができなくなる。
そうなると必然的にSidekiqのWebUIも見ることができなくなり、account delete
アクティビティが流れ切ったのか確認する術がなくなってしまう。
Sidekiqはキューの管理にRedisを使用しているので、Redisのコマンドラインツールredis-cli
を用いて、進捗を確認することができる。
$ 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.
# 保持しているすべての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
以上