Ruby による SFTP ファイルポーリングの自動化
Net::SFTP を使って信頼できる受け渡し用ディレクトリをポーリングし、完全なファイルをローカルディレクトリに公開します。以下のスクリプトはサーバーのホスト鍵を検証し、ダウンロードを一時保存してからローカルファイルを置き換えます。削除を明示的に有効にしない限り、リモートファイルは保持します。60 秒待機するたびに対象の全ファイルを再びポーリングします。インポート済みのファイルは記録しません。
前提条件とセットアップ
この例では、Linux、OpenSSL 対応の Ruby 3.4.10、Bundler 2.6.9 を使います。Ruby 3.4 はメンテナンス中のリリース系列です。Ruby 3.1 と 3.2 はサポートが終了しています。gem のネイティブ拡張機能用に、コンパイラーと Ruby の開発用ヘッダーを用意してください。
既存の SFTP アカウントが必要です。管理者によって公開鍵が承認され、受け渡し用ディレクトリの読み取りと一覧取得が許可されている必要があります。サーバー設定と鍵の承認については、OpenSSH サーバーマニュアルを参照してください。この無人実行の例では、ファイルシステムのアクセス権で保護した、専用の暗号化されていない秘密鍵を使います。サーバーの公開ホスト鍵またはフィンガープリントは、信頼できる経路で管理者から入手してください。ssh-keyscan で候補を取得する場合は、専用の known_hosts ファイルに追加する前に検証してください。スキャンだけでは信頼性を確認できません。標準以外のポートを使う場合、ホストエントリーには [hostname]:port を使う必要があります。
新しいディレクトリで作業を始め、以下を Gemfile として保存してください。ここでは、Net::SSH 7.3.0 の Ed25519 依存関係を含め、以下のバージョンを使います。
source 'https://rubygems.org'
gem 'net-sftp', '4.0.0'
gem 'net-ssh', '7.3.0'
gem 'ed25519', '1.4.0'
gem 'bcrypt_pbkdf', '1.1.1'
gem 'base64', '0.3.0'
そのディレクトリで bundle をインストールし、生成された
Gemfile.lock をスクリプトと一緒に保持してください。
bundle install
ローカルの保存先は、このインポーターだけが管理するディレクトリにしてください。ファイルの提供側は、ドットで始まる名前でアップロードを完了し、名前を変更して公開した後は、そのバイト列を変更してはいけません。このスクリプトはリモートファイルをロックせず、読み取り中の変更も検出しません。
ファイルポーラーの作成
以下を sftp_poller.rb として、Gemfile と同じ場所に保存してください。REMOTE_DIR 直下の通常ファイルをインポートし、ドットファイル、サブディレクトリ、シンボリックリンクはスキップします。ダウンロードに成功すると、同名の既存ローカルファイルを置き換えます。失敗した場合は、以前のローカルファイルをそのまま残します。
このポーラーは、ダウンロード後にリモートサーバー上の各ファイルを削除できます。削除は元に戻せず、共有の受け渡し用ディレクトリには不適切な動作です。デフォルトでは無効です。DELETE_AFTER_DOWNLOAD=true を設定するのは、このスクリプトがリモートディレクトリを専有する場合だけにしてください。ただし、有効化するだけでは不十分です。ダウンロードから削除までの間に提供側が同じ名前のファイルを書き換えると、インポートしていない版を削除してしまいます。提供側が各ファイルを一度だけ書き込み、その名前を再利用しない場合に限り有効にしてください。
require 'net/sftp'
require 'logger'
require 'json'
require 'tempfile'
require 'fileutils'
require 'time' # Time#iso8601, used by the log formatter below
# Configuration constants
SFTP_HOST = ENV.fetch('SFTP_HOST')
SFTP_USER = ENV.fetch('SFTP_USER')
SFTP_PORT = ENV.fetch('SFTP_PORT', 22).to_i
REMOTE_DIR = ENV.fetch('REMOTE_DIR')
LOCAL_DIR = ENV.fetch('LOCAL_DIR', './downloads')
SSH_KEY = ENV.fetch('SSH_KEY_PATH')
KNOWN_HOSTS = ENV.fetch('SSH_KNOWN_HOSTS', File.expand_path('~/.ssh/known_hosts'))
# Removing the remote copy cannot be undone, so it has to be asked for explicitly.
DELETE_AFTER_DOWNLOAD = ENV.fetch('DELETE_AFTER_DOWNLOAD', 'false') == 'true'
# Initialize structured logger
STDOUT.sync = true
logger = Logger.new(STDOUT)
logger.formatter = proc do |severity, datetime, progname, msg|
JSON.dump(
timestamp: datetime.iso8601,
severity: severity,
message: msg,
service: 'sftp-poller'
) + "\n"
end
def download_file(sftp, remote_file, final_path, logger)
temp_path = nil
begin
# Stage inside the destination directory so the final rename stays on one filesystem. That is
# what makes it atomic; Tempfile's default directory is usually a different mount.
temp = Tempfile.create('sftp-download', File.dirname(final_path))
temp_path = temp.path
temp.close
sftp.download!(remote_file, temp_path)
File.rename(temp_path, final_path)
temp_path = nil
logger.info({ action: 'download_complete', file: remote_file, destination: final_path })
true
rescue Net::SFTP::StatusException => e
logger.error({ action: 'download_failed', file: remote_file, error: e.message, code: e.code })
false
rescue SystemCallError, IOError => e
# A local failure (permissions, a full disk) must not take the whole poller down.
logger.error({ action: 'download_failed', file: remote_file, error: e.message })
false
ensure
File.unlink(temp_path) if temp_path && File.exist?(temp_path)
end
end
def with_retries(max_attempts: 3, base_delay: 1, logger:)
attempt = 0
begin
attempt += 1
yield
rescue Net::SSH::AuthenticationFailed => e
logger.error({ action: 'authentication_failed', error: e.message })
raise
rescue Errno::ECONNREFUSED, Net::SSH::ConnectionTimeout => e
if attempt < max_attempts
delay = base_delay * (2 ** (attempt - 1))
logger.warn({ action: 'retry_attempt', attempt: attempt, delay: delay, error: e.message })
sleep delay
retry
end
logger.error({ action: 'max_retries_reached', error: e.message })
raise
end
end
# Entry names come from the server, so only a plain basename may be joined onto REMOTE_DIR and
# LOCAL_DIR. A name such as `a/../../escaped.txt` is neither hidden nor a directory, yet it reads
# outside REMOTE_DIR, writes outside LOCAL_DIR, and with deletion enabled removes the wrong remote
# file. Reject those names rather than trying to repair them.
def plain_basename?(name)
return false if name.nil? || name.empty?
return false if name.include?('/') || name.include?('\\')
return false if name == '.' || name == '..'
File.basename(name) == name
end
def poll_sftp(logger)
with_retries(logger: logger) do
Net::SFTP.start(
SFTP_HOST,
SFTP_USER,
port: SFTP_PORT,
keys: [SSH_KEY],
keys_only: true,
config: false,
use_agent: false,
auth_methods: ['publickey'],
non_interactive: true,
timeout: 10,
# Refuse to connect to a host whose key is not already trusted.
verify_host_key: :always,
user_known_hosts_file: KNOWN_HOSTS,
global_known_hosts_file: []
) do |sftp|
logger.info({ action: 'connection_established', host: SFTP_HOST, directory: REMOTE_DIR })
sftp.dir.foreach(REMOTE_DIR) do |entry|
break if @shutdown
# A leading dot is usually a producer's partial upload, so skip those quietly.
next if entry.name.start_with?('.')
unless plain_basename?(entry.name)
logger.warn({ action: 'entry_rejected', file: entry.name })
next
end
# download! raises on directories, which would otherwise break every future cycle too.
next unless entry.attributes.file?
remote_file = File.join(REMOTE_DIR, entry.name)
local_file = File.join(LOCAL_DIR, entry.name)
next unless download_file(sftp, remote_file, local_file, logger)
next unless DELETE_AFTER_DOWNLOAD
begin
sftp.remove!(remote_file)
logger.info({ action: 'remote_file_removed', file: remote_file })
rescue Net::SFTP::StatusException => e
logger.error({ action: 'remove_failed', file: remote_file, error: e.message })
end
end
end
end
end
# Ensure the local download directory exists
FileUtils.mkdir_p(LOCAL_DIR)
# Set up signal handling for graceful shutdown
@shutdown = false
Signal.trap('TERM') { @shutdown = true }
Signal.trap('INT') { @shutdown = true }
# Main polling loop with graceful shutdown
until @shutdown
poll_sftp(logger)
break if @shutdown
logger.info({ action: 'polling_wait', delay: 60 })
60.times do
break if @shutdown
sleep 1
end
end
logger.info({ action: 'shutdown_complete' })
以下の接続情報と絶対パスを置き換え、スクリプトのディレクトリから実行してください。SSH_KEY_PATH は秘密鍵ファイルを指定します。鍵の内容を環境変数に入れないでください。
SFTP_HOST=sftp.example.com \
SFTP_PORT=22 \
SFTP_USER=importer \
REMOTE_DIR=/drop \
LOCAL_DIR=/srv/sftp-import/downloads \
SSH_KEY_PATH=/srv/sftp-import/id_ed25519 \
SSH_KNOWN_HOSTS=/srv/sftp-import/known_hosts \
DELETE_AFTER_DOWNLOAD=false \
bundle exec ruby sftp_poller.rb
スキャンが成功すると、JSON ログには connection_established、インポートしたファイルごとの download_complete イベント、polling_wait が含まれます。後続の処理を接続する前に、指定された保存先ファイルをバイト列も含めて確認してください。完了イベントは、ローカルでの名前変更が成功したことを示します。後続処理やオプションのリモート削除が成功したことは意味しません。空のファイルも有効なインポート対象です。
スクリプトの仕組み
このスクリプトは、以下の重要な機能を実装しています。
-
環境変数による設定: セキュリティのベストプラクティスに従い、機密性の高い設定には環境変数を使います。
-
構造化ログ: イベントごとに JSON オブジェクトを出力します。イベントのフィールドは文字列にシリアライズせず、
messageの下にネストするため、ログ集約ツールでインデックス化できます。 -
アトミックなファイル操作: 各ダウンロードを保存先と同じ場所に一時保存し、名前を変更して公開します。名前変更がアトミックなのは単一ファイルシステム内に限られるため、一時ファイルは
LOCAL_DIRに作成し、/tmpには作成しません。利用側はsftp-downloadで始まる名前を無視する必要があります。これらは一時ファイルです。この接頭辞は予約し、入力ファイル名には使わないでください。アトミックに公開されるのは最終的なファイル名だけです。また、Tempfile.createはモード0600を使い、名前変更後も維持されます。別のアカウントがインポート済みファイルを読む必要がある場合は、名前変更の前にFile.chmodを追加してください。これが成り立つのは、スクリプトがLOCAL_DIRを専有する場合だけです。他の処理が書き込まないディレクトリを指定し、利用側には内部にサブディレクトリを作成させず、ファイルを外へ移動させてください。アトミック性はリモート側にまでは及びません。読み取り中に提供側がファイルを書き換えると、二つの版が混在した内容を受け取ります。そのため、提供側には一時的な名前でアップロードさせ、全バイトの転送後に名前を変更してREMOTE_DIRに配置させてください。アトミックな置き換えは、電源断に対する永続性の保証ではありません。スクリプトはfsyncを呼び出しません。ここで使うアクセス権と明示的なクリーンアップについては、Ruby の Tempfile ドキュメントで説明されています。 -
信頼できないエントリー名:
plain_basename?は、サーバーが返す一覧のうち、単純なファイル名ではないものをすべて拒否します。これがないと、a/../../escaped.txtのような名前はドットファイルの検査とattributes.file?の両方を通過します。その後、パスとして結合されるとLOCAL_DIRの外に抜け出し、REMOTE_DIRの外部のパスを読み取ります。削除が有効なら、指定していないファイルまで削除します。 -
エラー処理: 接続拒否と接続タイムアウトでは、一秒、次に二秒待機し、最大三回まで接続を試みます。個別ダウンロード中の SFTP ステータスエラーとローカルファイルシステムエラーは記録してスキップし、次のエントリーをインポートできます。未知または変更されたホスト鍵、認証失敗、ディレクトリ一覧の取得失敗、SSH 接続の切断が発生すると、プロセスは終了します。再起動前に原因を修正し、ホスト検証を回避しないでください。
-
終了処理: Ctrl+C または
SIGTERMで終了を要求します。ポーリングの待機中は、一秒ごとに要求を確認します。転送中は現在のファイルと、有効化されている場合はその削除を完了し、次のエントリーに進む前に停止します。接続タイムアウトが制限するのは初期接続の確立であり、転送全体ではないため、サーバーが応答しなくなると終了が遅れることがあります。通常の例外では一時ファイルをクリーンアップしますが、SIGKILLやマシンのクラッシュでは実行できません。強制停止後に残ったsftp-download*ファイルは、インポーターが停止している間だけ削除してください。 -
任意のリモートクリーンアップ: 重複処理を防ぐため、ダウンロードに成功したファイルをリモートサーバーから削除します。ただし、
DELETE_AFTER_DOWNLOAD=trueの場合に限ります。削除対象は名前であり、ダウンロードした版ではありません。そのため、上の警告と同じく、一度だけ書き込む運用に依存します。無効のまま使う場合は、インポート済みファイル名のローカル台帳など、再処理を避ける別の手段が必要です。
本番環境へのデプロイ
上の実行例はフォアグラウンドプロセスです。プロセス監視下で動かす前に、利用側で重複処理を避ける方法を決め、プロセス終了だけでなくファイル単位のエラーも監視し、ダウンロード用の永続ストレージを用意してください。保存先ごとに実行するインポーターは一つだけにしてください。以下はパッケージ化の検討事項であり、完全なデプロイ設定ではありません。
Systemd の利用
サービスの実行アカウントには、鍵、信頼済みホストファイル、スクリプト、インストール済み bundle の読み取り権限と、保存先への書き込み権限が必要です。スクリプトのディレクトリを作業ディレクトリにし、Bundler 経由で起動してください。停止猶予時間は転送に合わせて設定してください。終了要求は進行中のダウンロードを中止しません。応答しないインポーターを監視ツールが最終的に強制終了すると、一時ファイルが残る場合があるため、復旧処理ではそれも考慮する必要があります。
docker の利用
メンテナンス中の Ruby イメージを使い、同じロック済み bundle をインストールし、認証情報はイメージの外に置いてください。鍵と信頼済みホストファイルは読み取り専用でマウントし、ダウンロードディレクトリはボリュームで永続化してください。停止シグナルが Ruby に届くことを確認してください。Docker の Linux でのデフォルト停止猶予時間はわずか 10 秒で、その後は SIGKILL を送信します。ワークロードに合わせて猶予時間を設定し、アイドル状態のコンテナーだけでなく、転送中の状態でもテストしてください。Docker の停止動作を参照してください。
セキュリティのベストプラクティス
-
ホスト鍵の検証:
- 未知または変更されたホスト鍵で接続を中止するよう、
verify_host_key: :alwaysを維持 - 初回接続時に提示された鍵ではなく、別経路で確認したフィンガープリントに基づいて
known_hostsを用意 - 実行ユーザーのホームディレクトリに依存せず、デプロイに
known_hostsを同梱(上記のSSH_KNOWN_HOSTS変数を参照)
- 未知または変更されたホスト鍵で接続を中止するよう、
-
SSH 鍵の管理:
- SSH 鍵の定期的なローテーション
- 固定した bundle には、Net::SSH 7.3.0 で Ed25519 鍵を使うためのオプションの gem を同梱
- 秘密鍵ファイルへのアクセスをインポーターのアカウントに制限
-
ネットワークセキュリティ:
- SFTP アクセスを特定の IP 範囲に制限
- 強力な暗号方式と鍵交換アルゴリズムの使用
- 停滞した転送の監視。初期接続のタイムアウトは転送期限ではない点に注意
-
ファイルアクセス:
- ローカルとリモートの両方で最小限のファイル権限を使用
- ファイルの整合性検証の実装
- 一時ファイルの適切なクリーンアップ
-
監視:
- ダウンロード失敗と接続問題に対するアラートの設定
- ディスク使用量の監視
- 処理メトリクスの追跡
まとめ
この Ruby スクリプトは、SFTP ファイルインポートを自動化するための出発点です。初期に問題となりやすいホスト鍵の検証、サーバーが制御するエントリー名、完全に書き込まれるか何も公開されないローカル書き込み、ポーリングループを終了させてはいけない障害に対応しています。再起動をまたぐ重複排除、ディスク容量の制限、動作報告が途絶えたポーラーへのアラートは、別途追加する必要があります。
すでに Transloadit をお使いの場合は、SFTP インポートのドキュメントを参照してください。
