systemd-nspawn(1)

名称

systemd-nspawn - デバッグ・テスト・ビルド用の名前空間コンテナを生成

書式

systemd-nspawn [OPTIONS...] [ COMMAND [ARGS...] ]

systemd-nspawn --boot [OPTIONS...] [ARGS...]

説明

systemd-nspawn を使うことで軽量な名前空間コンテナの中でコマンドや OS を実行することができます。多くの点で chroot(1) と似ていますが、ファイルシステム階層やプロセスツリー、様々な IPC サブシステムやホスト・ドメイン名まで完全に仮想化されるため、chroot よりも強力です。

systemd-nspawn は --directory= コマンドラインオプションを使うことでオペレーティングシステムツリーを含むあらゆるディレクトリツリーで呼び出すことができます。--machine= オプションを使用すると複数の場所から OS ツリーが自動的に検索されます。特にシステムにコンテナイメージを置くときには /var/lib/machines が推奨されています。

chroot(1) とは対照的に、systemd-nspawn はコンテナの中で完全な Linux ベースのオペレーティングシステムを起動することができます。

systemd-nspawn はコンテナの中で様々なカーネルインターフェイスを読み取り専用に制限します。例えば /sys や /proc/sys、/sys/fs/selinux などです。コンテナの中からホストのネットワークインターフェイスやシステムクロックを変更することはできません。デバイスノードも作成不可能です。コンテナの中からホストシステムを再起動したりカーネルモジュールをロードすることも出来ないようになっています。

dnf(8) や debootstrap(8)、pacman(8) などのツールを使うことで systemd-nspawn コンテナ用にファイルシステム階層として適した OS ディレクトリツリーをセットアップすることができます。これらのコマンドの実行方法について詳しくはサンプルセクションを見てください。

安全確認として systemd-nspawn はコンテナの起動前にコンテナツリーの /usr/lib/os-release や /etc/os-release が存在するか確認します (os-release(5) を参照)。コンテナの OS が古すぎて含まれているファイルが古い場合、コンテナツリーに手動でファイルを追加する必要があります。

systemd-nspawn はインタラクティブなコマンドラインから直接呼び出すだけでなく、システムサービスとしてバックグラウンドで実行することができます。このモードでは各コンテナのインスタンスは各々サービスインスタンスとして実行されます。簡単に実行できるようにデフォルトのテンプレートユニットファイル systemd-nspawn@.service が存在します。インスタンス識別子としてコンテナの名前を指定します。コマンドラインでインタラクティブに実行するのではなくテンプレートユニットファイルを使って systemd-nspawn を起動した場合、異なるデフォルトオプションが適用されるので注意してください。特に重要なこととして、インタラクティブなコマンドラインから systemd-nspawn を実行したときはデフォルトではない、--boot がテンプレートユニットファイルによって使われます。デフォルトオプションの違いについては、サポートされている様々なオプションと共に下で説明しています。

machinectl(1) ツールを使うことで様々なコンテナの操作を行うことができます。特に systemd-nspawn@.service テンプレートユニットファイルを使ってシステムサービスとしてコンテナを実行するときに使いやすいコマンドが揃っています。

各コンテナには拡張子が .nspawn の設定ファイルを作成でき、コンテナを実行する時の追加設定を記述できます。詳しくは systemd.nspawn(5) を見てください。設定ファイルは systemd-nspawn@.service テンプレートユニットファイルで使われるデフォルトオプションを上書きするため、通常はテンプレートファイルに直接変更を加える必要はありません。

systemd-nspawn はコンテナの秘密のファイルシステムを /dev や /run などにマウントします。コンテナの外からは閲覧することができず、ファイルシステムの中身はコンテナの終了時に消去されます。

同じディレクトリツリーから systemd-nspawn コンテナを2つ実行したとしても、互いのコンテナのプロセスはわからないので注意してください。2つのコンテナにおける PID 名前空間の分離は完全であり、起動元のファイルシステム以外にコンテナが共有するランタイムオブジェクトはほとんどありません。実行中のコンテナでログインセッションを追加したいときは machinectl(1) の login か shell コマンドを使ってください。

systemd-nspawn は Container Interface 1 の仕様を実装しています。

実行時、systemd-nspawn で起動したコンテナは systemd-machined(8) サービスで登録されてコンテナの実行が追跡されます。systemd-machined(8) はコンテナを操作するためのプログラミングインターフェイスを提供します。

オプション

オプション -b が指定されると、引数は init プログラムの引数として使われます。指定しなかった場合、COMMAND はコンテナの中で起動するプログラムを指定します。残りの引数はプログラムの引数として扱われます。--boot を使用せず引数も指定しなかった場合、コンテナの中でシェルが起動します。

以下のオプションを利用できます:

-D, --directory=

コンテナのルートファイルシステムとして使用するディレクトリ。

--directory= も --image= も指定しなかった場合、--machine= で指定されたマシン名と同じ名前のディレクトリを検索してディレクトリが決定されます。正確な検索パスについては machinectl(1) の "Files and Directories" セクションを参照してください。

--template=

コンテナのルートディレクトリのテンプレートとして使用するディレクトリあるいは "btrfs" サブボリューム。このオプションを指定していてコンテナのルートディレクトリ (--directory= で指定) が存在しない場合、"btrfs" スナップショット (サポートされている場合) あるいはプレーンディレクトリ (サポートされていない場合) としてディレクトリが作成されてテンプレートツリーからファイルが生成されます。理想的には、指定されたテンプレートパスが "btrfs" サブボリュームのルートだった場合、シンプルな copy-on-write スナップショットが取得され、一瞬でルートディレクトリが作成されます。指定されたテンプレートパスが "btrfs" サブボリュームのルートではなかった場合 (あるいは "btrfs" ファイルシステムでもない場合)、ツリーがコピーされるため (ファイルシステムが copy-on-write をサポートしている場合、copy-on-write が使われる可能性があります)、ディレクトリを作成するのにかかる時間が大幅に増える可能性があります。--image= や --ephemeral と一緒に指定することはできません。

このスイッチではホスト名やマシン ID などのインスタンスを識別する設定は変わらないので注意してください。

-x, --ephemeral

指定した場合、ファイルシステムの一時的なスナップショットを使ってコンテナが実行され、コンテナの終了時に即座に消去されます。--template= と一緒に指定することはできません。

このスイッチではホスト名やマシン ID などのインスタンスを識別する設定は変わらないので注意してください。

-i, --image=

コンテナのルートディレクトリをマウントするディスクイメージ。通常のファイルまたはブロックデバイスノードを指定します。ファイルまたはデバイスには以下のいずれかが含まれている必要があります:

  • MBR パーティションテーブルと、タイプ 0x83 で bootable とマークされたシングルパーティション。

  • GUID パーティションテーブル (GPT) と、タイプ 0fc63daf-8483-4772-8e79-3d69d8477de4 のシングルパーティション。

  • GUID パーティションテーブル (GPT) と、コンテナのルートディレクトリとしてマウントされるようマークしたルートパーティション。任意で、GPT イメージにはホーム・サーバーデータパーティションを含めることができ、コンテナの適切な場所にマウントされます。全てのパーティションは Discoverable Partitions Specification 2 で定義されているパーティションタイプで識別します。

  • パーティションテーブルなし、イメージ全体にまたがるシングルファイルシステム。

GPT イメージの場合、EFI システムパーティション (ESP) が発見されると、自動的に /efi (またはフォールバックの /boot) にマウントされます (同名のディレクトリが存在していて空の場合)。

LUKS で暗号化されたパーティションは自動的に復号化されます。また、GPT イメージでは --root-hash= オプションによってハッシュパーティションのルートハッシュが指定されている場合、dm-verity データ整合性ハッシュパーティションが設定されます。

他のパーティション、不明なパーティションやスワップパーティションなどはマウントされません。--directory= や --template= と一緒に指定することはできません。

--root-hash=

16進数でデータ整合性 (dm-verity) ルートハッシュを指定します。使用するイメージに適切な整合性データが含まれている場合 (上を参照)、このオプションによって dm-verity によるデータ整合性チェックが有効になります。指定するハッシュは整合性データのルートハッシュと一致している必要があります。通常は256ビット以上です (SHA256 の場合、16進数では64文字になります)。このオプションが指定されなかった場合、イメージファイルに "user.verity.roothash" 拡張ファイル属性が設定されていたときは (xattr(7) を参照)、16進数の文字列としてルートハッシュが読み込まれます。拡張ファイル属性がないときは (あるいはファイルシステムによってサポートされていない場合)、イメージファイルと同じディレクトリに .roothash 拡張子のファイルが存在していてファイル名が同じ場合、同じく16進数の文字列として自動的に読み込まれて使用されます。

-a, --as-pid2

PID 1 (init) ではなく ID (PID) 2 プロセスとしてシェルまたは指定したプログラムを起動します。デフォルトでは、このオプションや --boot が使われなかった場合、選択したプログラムは PID 1 のプロセスとして実行されます。UNIX では PID 1 は特殊な意味を持ちます。例えば、PID 1 プロセスは親となった全てのプロセスを回収して、sysvinit 互換のシグナル処理を実装する必要があります (例えば SIGINT では再起動、SIGTERM では再実行、SIGHUP では設定のリロードなどを行います)。--as-pid2 を使用すると最小限のスタブ init プロセスが PID 1 で起動して、選択したプログラムは PID 2 で実行されます (特殊な機能を実装する必要がなくなります)。スタブ init プロセスは必要に応じてプロセスを回収してシグナルに反応します。コンテナの中で任意のコマンドを実行するときはこのモードを使用することを推奨します。使用しないときはコマンドを PID 1 として正しく実行できるように改造しなければなりません。つまり、コマンドが init やシェル実装でないかぎり、ほとんど全てのコマンドでこのスイッチを使用するべきです。init やシェルは大抵 PID 1 として実行できるようになっています。このオプションは --boot と組み合わせることができません。

-b, --boot

シェルやユーザー指定のプログラムの代わりに、自動的に init プログラムを検索して PID 1 として実行します。このオプションを使用した場合、コマンドラインの引数は init プログラムの引数として使われます。このオプションは --as-pid2 と組み合わせることができません。

以下の表は様々な実行モードと --as-pid2 (上を参照) の関係を説明しています:

表 1. 実行モード

スイッチ

説明

--as-pid2 と --boot のどちらも指定しない

指定したパラメータはコマンドラインとして解釈され、コンテナの中で PID 1 として実行される。

--as-pid2 を指定する

指定したパラメータはコマンドラインとして解釈され、コンテナの中で PID 2 として実行される。 スタブ init プロセスが PID 1 として実行される。

--boot を指定する

init プログラムが自動的に検索されて、コンテナの中で PID 1 として実行される。 指定したパラメータはプロセスの実行パラメータとして使用される。

注釈

systemd-nspawn@.service テンプレートユニットファイルを使用するときは --boot がデフォルトの実行モードです。

--chdir=

コンテナの中でプロセスを実行する前に指定した作業ディレクトリに移動します。コンテナのファイルシステム名前空間の絶対パスで指定します。

--pivot-root=

指定したディレクトリをコンテナの中の / にして、コンテナの古いルートはアンマウントするか、他の指定したディレクトリの中心になります。パスをひとつだけ指定した場合、指定したパスが / になって古いルートはアンマウントされます。もしくは新しいルートパスをコロンで区切って古いルートのマウント先を指定した場合、新しいルートパスが / になり、古い / は別のディレクトリになります。パスはどちらも絶対パスで、コンテナのファイルシステム名前空間で解決されます。

このオプションはブートするディレクトリが複数存在するコンテナのためにあります。例えば、複数の OSTree 3 をデプロイする場合など。通常時にルートとしてマウントするディレクトリを選択してコンテナの PID 1 を起動する、ブートローダーと初期 RAM ディスクの挙動をエミュレートしています。

-u, --user=

コンテナに移行後、コンテナのユーザーデータベースで定義されている指定ユーザーに変わります。他の systemd-nspawn の機能と同じように、これはセキュリティ機能ではなく偶発的に破壊的な操作を行ってしまわないための防護として用意されています。

-M, --machine=

コンテナのマシンの名前を設定します。この名前は実行時に (machinectl(1) などのツールで) コンテナを識別するのに使うことができます。また、コンテナのホスト名を初期化するのにも使われます (ただしコンテナによって上書きされる可能性はあります)。指定しなかった場合、コンテナのルートディレクトリのパスの最後の部分が使われます。--ephemeral モードが選択されているときはランダムな識別子が後ろに付きます。選択されたルートディレクトリがホストのルートディレクトリの場合はホストのホスト名がデフォルトで使用されます。

--uuid=

指定された UUID をコンテナに設定します。init システムは UUID で /etc/machine-id を初期化します (ファイルがまだ設定されていない場合)。このオプションが効果を発揮するのはコンテナの /etc/machine-id が作成されていない場合だけなので注意してください。

-S, --slice=

デフォルトの machine.slice の代わりに、指定された slice でコンテナを作成します。マシンが独自の scope ユニットで実行される場合 (--keep-unit が使われていない場合) にのみ適用されます。

--property=

マシンに登録する scope ユニットのユニットプロパティを設定します。マシンが独自の scope ユニットで実行される場合 (--keep-unit が使われていない場合) にのみ適用されます。systemctl set-property と同じ形式でユニットプロパティを指定します。コンテナのメモリ制限などを設定するのに有用。

--private-users=

ユーザー名前空間を制御します。有効にした場合、コンテナはプライベートな UNIX ユーザーとグループ id (UID と GID) で動作するようになります。また、コンテナで使用されるプライベート UID/GID (コンテナのルートユーザー 0 以上) がホストで他の用途に使われていない UID/GID (ホストの UID/GID 65536 以上の範囲) にマッピングされます。パラメータは以下のように指定します:

  1. コロンで区切った数字をひとつまたはふたつ指定した場合、ユーザー名前空間がオンになります。最初のパラメータはコンテナに割り当てられる最初のホストの UID/GID を指定し、二番目のパラメータはコンテナに割り当てられる UID/GID の数を指定します。二番目のパラメータを省略した場合、65536個の UID/GID が割り当てられます。

  2. パラメータを省略した場合、あるいは true を指定した場合、ユーザー名前空間がオンになります。使用する UID/GID の範囲はコンテナのディレクトリツリーのルートディレクトリのファイル所有者から自動的に決定されます。このオプションを使用するときは、ディレクトリツリーをあらかじめ用意してください。そしてディレクトリツリーのファイルとディレクトリが全て使用したい範囲の UID/GID によって所有されていることを確認してください。また、使用するファイルの ACL が適切な範囲の UID/GID を排他的に参照していることを確認してください。このモードを使用する場合、コンテナに割り当てられる UID/GID の数は65536個になり、ルートディレクトリの UID/GID は 65536 の倍数である必要があります。

  3. パラメータが false の場合、ユーザー名前空間はオフになります。デフォルトの設定です。

  4. 特殊な値 "pick" はユーザー名前空間をオンにします。この場合 UID/GID の範囲は自動的に選択されます。最初に、コンテナのディレクトリツリーのファイル所有者が読み込まれます。そしてシステムで他の用途に使われていないかどうか確認されます (特に、他のコンテナが使用していないこと)。チェックして問題なければ、"yes" が指定されたときと同じようにこの方法で UID/GID の範囲が決まります。チェックで問題があった場合 (ルートディレクトリのファイル所有者で示される UID/GID の範囲が他の場所で使われている場合)、ホストの UID/GID の 524288 から 1878982656 までの中からランダムで未使用の新しい65536個の UID/GID の範囲が選ばれます (最初の数字はかならず 65536 の倍数になります)。この設定を使うと --private-users-chown も有効になり (下を参照)、コンテナのディレクトリツリーのファイルとディレクトリが選択された範囲の適当なユーザーによって所有されるようになります。このオプションを使うことでユーザー名前空間の挙動が完全に自動化されます。まだ使用したことがないコンテナイメージを初めて呼び出したとき、新しい UID/GID が選択され、(高価な) ファイル所有権変更操作が行われます。ただし、2回目以降のコンテナ実行は安価になります (選択された UID/GID の範囲を別の用途で割り当てないかぎり)。

コンテナの利用可能な UID/GID の範囲が16ビットを上回るように、コンテナには最低でも65536個の UID/GID を割り当てることが推奨されています。セキュリティを高めるために、重複する UID/GID を複数のコンテナに割り当てないでください。ホストの32ビットの UID/GID のうち上位16ビットをコンテナの識別子として使用し、下位の16ビットで使用するコンテナの UID/GID をエンコードすると良いでしょう。--private-users=pick オプションを使用するとこの挙動が適用されます。

ユーザー名前空間を使うとき、各コンテナに割り当てられる GID の範囲は常に UID の範囲と同じになります。

大抵の場合、--private-users=pick オプションを使用することを推奨します。コンテナのセキュリティを大いに強化することができ、大体の場合は全て自動的に操作してくれるためです。

選択された UID/GID の範囲は /etc/passwd や /etc/group には書き込まれないので注意してください。事実、範囲の割当はどこにも永続的には保存されません。例外はコンテナのファイルとディレクトリのファイル所有権だけです。

ユーザー名前空間を使用する場合、ディスクのファイル所有権が名前空間に反映され、コンテナのファイルやディレクトリは全てコンテナの実効的なユーザーとグループ ID によって所有されます。コンテナイメージからファイルをコピーするときは UID/GID のずれにあわせて数字の UID/GID を補正する必要があるので注意してください。

--private-users-chown

指定した場合、コンテナのディレクトリツリーの全てのファイルとディレクトリがコンテナ用に選択された適切な UID/GID によって所有されるようになります (上を参照)。コンテナのディレクトリツリー全体で再帰的に操作が繰り返されるため、リソース消費が大きくなる可能性があります。ファイルの所有権だけでなく、ファイルの ACL も同じく設定されます。

--private-users=pick を使用したときは自動的にこのオプションも有効になります。ユーザー名前空間を使わないときはこのオプションは効果がありません。

-U

カーネルがユーザー名前空間機能をサポートしている場合、--private-users=pick --private-users-chown --private-users=no と同じ効果をもたらします。

systemd-nspawn@.service テンプレートユニットファイルを使うときは -U はデフォルトで使用されます。

注釈

--private-users-chown (または -U) によるファイルシステムの変更は以下のように最初の UID を 0 として操作を再実行することで元に戻せます:

systemd-nspawn ... --private-users=0 --private-users-chown

--private-network

ホストからコンテナのネットワークを切断します。コンテナの全てのネットワークインターフェイスが利用不可能になります。例外はループバックデバイスと --network-interface= と --network-veth で指定したインターフェイスだけです。このオプションを指定した場合、コンテナのケイパビリティに CAP_NET_ADMIN ケイパビリティが追加されます。ケイパビリティの追加は --drop-capability= を使うことで無効化できます。このオプションを指定しない場合 (あるいは下のオプションのどれかを使用した場合)、コンテナはホストのネットワークに完全にアクセスできるようになります。

--network-namespace-path=

コンテナが動作するカーネルネットワーク空間を表すファイルのパスを指定します。指定するパスは /proc/$PID/ns/net 下のネットワーク名前空間でなければなりません (バインドマウントすることもできます)。コンテナが指定したネットワーク名前空間を使うようになります。ユースケースとしては ip-netns(8) で作成した /run/netns のネットワーク名前空間を指定するなどが考えられます (例: --network-namespace-path=/run/netns/foo)。このオプションは --private-network や --network-interface= など他のネットワーク関連のオプションと組み合わせて使うことはできません。

--network-interface=

コンテナに指定したネットワークインターフェイスを割り当てます。指定したネットワークは呼び出した名前空間からは削除されコンテナの中に配置されます。コンテナの終了時に、インターフェイスはホストの名前空間に戻されます。--network-interface= を使うと黙示的に --private-network も有効になります。このオプションは複数使用して複数のネットワークインターフェイスをコンテナに追加することが可能です。

--network-macvlan=

指定された Ethernet ネットワークインターフェイスの "macvlan" インターフェイスを作成してコンテナに追加します。"macvlan" インターフェイスは仮想のインターフェイスで、既存の物理 Ethernet リンクに二番目の MAC アドレスを追加します。コンテナのインターフェイスはホストのインターフェイスと同じ名前に "mv-" が前に付くようになります。--network-macvlan= を使うと黙示的に --private-network も有効になります。このオプションは複数使用して複数のネットワークインターフェイスをコンテナに追加することが可能です。

--network-ipvlan=

指定された Ethernet ネットワークインターフェイスの "ipvlan" インターフェイスを作成してコンテナに追加します。"ipvlan" インターフェイスは "macvlan" インターフェイスと同じように仮想のインターフェイスで、指定したインターフェイスと同じ MAC アドレスを使用します。コンテナのインターフェイスはホストのインターフェイスと同じ名前に "iv-" が前に付くようになります。--network-ipvlan= を使うと黙示的に --private-network も有効になります。このオプションは複数使用して複数のネットワークインターフェイスをコンテナに追加することが可能です。

-n, --network-veth

ホストとコンテナの間に仮想 Ethernet リンク ("veth") を作成します。Ethernet リンクのホスト側はコンテナの名前の前に "ve-" が付いたネットワークインターフェイスで利用することができます (--machine= で指定できます)。Ethernet リンクのコンテナ側の名前は "host0" となります。--network-veth オプションを使うと黙示的に --private-network も有効になります。

systemd-networkd.service(8) はデフォルトでホスト側のインターフェイスにマッチするネットワークファイル /usr/lib/systemd/network/80-container-ve.network が含まれており、DHCP で作成された仮想リンクの自動アドレスプロビジョニングが有効になって、ホストの外部ネットワークインターフェイスに自動的に IP ルーティングされます。また、コンテナ側のインターフェイスにマッチする /usr/lib/systemd/network/80-container-host0.network も含まれており、DHCP で自動的にクライアントにアドレスが割り当てれる設定が書かれています。ホストとコンテナの両方で systemd-networkd を動作させている場合、コンテナからホストへの IP 通信が自動的に確立して、外部ネットワークにも接続できるようになっています。

systemd-nspawn@.service テンプレートユニットファイルを使用する場合、--network-veth はデフォルトで使用されます。

--network-veth-extra=

ホストとコンテナ間の仮想 Ethernet リンクを追加します。コロンで区切ってホストのインターフェイス名とコンテナのインターフェイス名を指定します。後者を省略した場合、ホストとコンテナの両方で同じ名前が割り当てられます。このスイッチは --network-veth と独立して使用することができ、複数指定することもできます。--network-bridge= は --network-veth-extra= で作成されたインターフェイスには効果が及ばないので注意してください。

--network-bridge=

指定した Ethernet ブリッジインターフェイスに --network-veth で作成した Ethernet リンクのホスト側を追加します。ブリッジデバイスの有効なネットワークインターフェイス名を指定してください。--network-bridge= を使用すると --network-veth が黙示的に有効になります。このオプションを使用した場合、Ethernet リンクのホスト側はプリフィックスとして "ve-" ではなく "vb-" を使用します。

--network-zone=

コンテナに仮想 Ethernet リンク ("veth") を作成して自動的に管理されている Ethernet ブリッジインターフェイスに追加します。ブリッジインターフェイスの名前は指定された引数の前に "vz-" が付いたものになります。名前を設定した最初のコンテナを起動したときにブリッジインターフェイスが自動的に作成されます。そして名前を設定した最後のコンテナが終了したときに自動的に削除されます。そのため、この方法で設定したブリッジインターフェイスは参照しているコンテナが実行中のときのみ存在することになります。このオプションは --network-bridge= とよく似ていますが、ブリッジデバイスを自動的に作成・削除するところが違いです。

この設定を使うことで共通の仮想 Ethernet ベースのブロードキャストドメインに関連するコンテナを複数配置することができ、ここではドメインのことを「ゾーン」と呼びます。コンテナはそれぞれゾーンのどれかに属することになりますが、ゾーンには任意の数のコンテナを含めることができます。ゾーンはそれぞれ名前を使って参照します。名前は自由に決めることが可能です ("vz-" を前に付けたときに有効なネットワークインターフェイスの名前になるかぎり)。様々なコンテナに同時に --network-zone= スイッチで同じ名前を指定してコンテナをひとつのゾーンにまとめることができます。

systemd-networkd.service(8) にはデフォルトでブリッジインターフェイスにマッチするネットワークファイル /usr/lib/systemd/network/80-container-vz.network が含まれており、DHCP で作成された仮想リンクの自動アドレスプロビジョニングが有効になって、ホストの外部ネットワークインターフェイスに自動的に IP ルーティングされます。大抵の場合は --network-zone= を使うことで複数のローカルコンテナをホストに完全自動で接続されて、外部ネットワークにも接続できるようになっています。

-p, --port=

プライベートネットワークが有効になっている場合、ホストの IP ポートをコンテナの IP ポートにマッピングします。1 から 65535 の範囲のホストのポート番号と、同じく 1 から 65535 の範囲のコンテナのポート番号を、コロンで区切ってプロトコルの識別子 ("tcp" または "udp") を指定します。プロトコルの識別子と区切りのコロンは省略することができ、その場合は "tcp" が使われます。コンテナのポート番号とコロンを省略した場合、ホストのポートと同じポートが使われます。このオプションは --network-veth, --network-zone=, --network-bridge= などでプライベートネットワークが使われている場合にのみ使用可能です。

-Z, --selinux-context=

コンテナのプロセスをラベリングするのに使用する SELinux セキュリティコンテキストを設定します。

-L, --selinux-apifs-context=

コンテナの仮想 API ファイルシステムのファイルをラベリングするのに使用する SELinux セキュリティコンテキストを設定します。

--capability=

コンテナに付与するケイパビリティをひとつまたは複数指定します。カンマで区切ってケイパビリティの名前を指定してください。詳しくは capabilities(7) を参照。どんなときでも次のケイパビリティは付与されるので注意してください: CAP_AUDIT_CONTROL, CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE, CAP_MKNOD, CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN, CAP_SYS_BOOT, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_RESOURCE, CAP_SYS_TTY_CONFIG。--private-network を指定した場合、CAP_NET_ADMIN も加わります。特殊な値として "all" を指定すると、全てのケイパビリティが付与されます。

--drop-capability=

コンテナから剥奪するケイパビリティをひとつまたは複数指定します。コンテナをデフォルトよりも少ないケイパビリティで動作させることができます (上を参照)。

--system-call-filter=

コンテナに適用するシステムコールフィルターを変更します。システムコールの名前あるいはグループの名前を空白で区切って指定します (後者は systemd-analyze(1) の syscall-filter コマンドのように、"@" を前に付けます)。指定したシステムコールは許可されます。指定するリストには任意で "~" を前に付けることができ、その場合は指定したシステムコールは禁止されます。このコマンドラインオプションを複数回使用した場合、設定したリストはまとめられます。許可・禁止両方のリスト ("~" プリフィックスがあるシステムコールのリストとそうではないリスト) を設定した場合、禁止リストが許可リストよりも優先されます。systemd-nspawn は常にシステムコールのホワイトリストを実装しており、このコマンドラインオプションはデフォルトのホワイトリストからエントリを ("~" プリフィックスの有無に応じて) 追加・削除します。--capabilities= を使って追加ケイパビリティを指定したときは適用されるシステムコールフィルターが変わるので注意してください。

--kill-signal=

nspawn が SIGTERM を受け取ったときにコンテナを正しくシャットダウンするためにコンテナの PID 1 に送信するプロセスシグナルを指定します。--boot を使用した場合のデフォルトは SIGRTMIN+3 です (systemd 準拠の init システムでは SIGRTMIN+3 でシャットダウンが行われます)。利用可能なシグナルについては signal(7) を参照してください。

コンテナのジャーナルをホストシステムから閲覧できるようにするか制御します。有効にした場合、ホストからコンテナのジャーナルファイルが閲覧できるようになります (ただし逆は不可能です)。"no", "host", "try-host", "guest", "try-guest", "auto" のどれかを指定してください。"no" の場合、ジャーネルはリンクされません。"host" の場合、ジャーナルファイルはホストのファイルシステムに保存され (/var/log/journal/machine-id)、サブディレクトリはコンテナの同じ場所にバインドマウントされます。"guest" の場合、ジャーナルファイルはゲストのファイルシステムに保存され (/var/log/journal/machine-id)、サブディレクトリはホストの同じ場所にシンボリックリンクが作成されます。"try-host" と "try-guest" はホストのジャーナルが永続的でない場合も保存に失敗しません。"auto" (デフォルト) の場合、/var/log/journal のサブディレクトリが存在すれば、コンテナにバインドマウントされます。サブディレクトリが存在しない場合、リンクは作成されません。事実上は、コンテナを一度でも "guest" または "host" で起動すれば、それ以降はデフォルトの "auto" を使っても永続的にジャーナルのリンクが機能します。

systemd-nspawn@.service テンプレートユニットファイルを使用するときは --link-journal=try-guest がデフォルトになります。

-j

--link-journal=try-guest と同じです。

--read-only

コンテナのルートファイルシステムを読み取り専用でマウントします。

--bind=, --bind-ro=

ホストのファイルやディレクトリをコンテナにバインドマウントします。パスをひとつだけ指定した場合、指定したパスはホストからコンテナの同じパスにマウントされます。コロンで区切ってパスを2つ指定した場合、最初に指定したパスがホストのリンク元 (ソース) となり、2番目のパスがコンテナのリンク先 (宛先) になります。さらにコロンで区切って3番目の値を指定した場合、リンク元・リンク先のパスとマウントオプションとなります。ソースパスは任意で "+" 文字を前に付けることができ、その場合、ソースパスはイメージのルートディレクトリからの相対パスと解釈されます。コンテナのイメージ内にバインドマウントを設定することが可能です。ソースパスは空文字を指定することもでき、その場合はホストの /var/tmp ディレクトリ下の一時ディレクトリが使用されます。一時ディレクトリはコンテナのシャットダウン時に自動的に削除されます。マウントオプションはカンマで区切ります。現在のところ、rbind と norbind が使用でき、再帰的なバインドマウントを使用するか通常のバインドマウントを使用するか制御できます。デフォルトは "rbind" です。バックスラッシュはエスケープとして処理されるため、パスの中にコロンが含まれる場合は ":" を使うことで指定できます。このオプションは複数回指定してバインドマウントポイントを複数作成することができます。--bind-ro= は読み取り専用のバインドマウントを作成します。

このオプションを --private-users と組み合わせて使用した場合、作成されるマウントポイントの所有者は nobody ユーザーとなります。マウントとファイル、ディレクトリはホストのユーザーとグループによって所有されることになりますが、コンテナには該当するユーザーもグループも存在しないため、ワイルドカードの UID 65534 (nobody) で認識されることになるためです。そのようなバインドマウントを作成するときは、--bind-ro= を使って読み取り専用にすることを推奨します。

--tmpfs=

tmpfs ファイルシステムをコンテナにマウントします。tmpfs インスタンスをマウントする先を絶対パスで指定します (その場合はディレクトリのアクセスモードは 0755 になり、所有権は root/root となります)。もしくは任意でパスとマウントオプションの文字列をコロンで区切って指定できます (その場合はアクセスモードと所有者は特に指定されないかぎりカーネルのデフォルトで選択されます)。このオプションは /var などのディレクトリを tmpfs としてマウントして、--read-only と組わせてステートレスシステムにしたい場合に有用です。バックスラッシュはエスケープとして処理されるため、パスの中にコロンが含まれる場合は ":" を使うことで指定できます。

--overlay=, --overlay-ro=

複数のディレクトリツリーをひとつの overlay ファイルシステムにまとめてコンテナにマウントします。ディレクトリツリーをコロンで区切ったリストとマウント先のマウントポイントを指定してください。

バックスラッシュはエスケープとして処理されるため、パスの中にコロンが含まれる場合は ":" を使うことで指定できます。

3つ以上のパスが指定された場合、最後に指定したパスがコンテナのマウントポイントになります。それ以前のパスは全てホストのディレクトリツリーになり、指定した順番で overlay ファイルシステムに合併されます。したがって一番左のパスが最下層のディレクトリツリーになり、それから右のパスが上部に重なっていく構造をとります。--overlay= の代わりに --overlay-ro= を使用した場合、読み取り専用の overlay ファイルシステムが作成されます。書き込み可能な overlay ファイルシステムが作成された場合、全ての変更は一番上のディレクトリツリー (最後から2番目に指定したパス) に書き込まれます。

パスが2つしか指定されなかった場合、2番目に指定したパスがホストから見て一番上層のディレクトリツリーとして使用され、同じくコンテナの overlay ファイルシステムのマウントポイントともなります。パスは最低でも2つ指定する必要があります。

ソースパスには任意で "+" 文字を前に付けることができます。その場合、イメージのルートディレクトリからの相対パスとして認識されます。一番上層のソースパスは空文字で指定でき、そのときはホストの /var/tmp 下の一時ディレクトリが使用されます。一時ディレクトリはコンテナのシャットダウン時に自動的に削除されます。この挙動はコンテナを動かすときに読み取り専用のコンテナディレクトリを作成したいときに有用です。例えば、"--overlay=+/var::/var" オプションを使うことで書き込み可能な一時ディレクトリを読み取り専用の /var ディレクトリの上に自動的に重ねることが可能です。

overlay ファイルシステムについて詳しくは overlayfs.txt 4 を参照してください。overlay ファイルシステムのセマンティクスは通常のファイルシステムとは大きく違うので注意してください。特に書き込み途中のファイルのデバイスと inode 情報は変わる可能性があり、プロセスからは古いバージョンのファイルが見えている可能性があります。このスイッチは自動的に最上位のディレクトリツリーから overlay ファイルシステムの "workdir=" マウントオプションを派生させるので注意してください。そのため、最上位のディレクトリはマウントポイントではないことが重要です (ワーキングディレクトリは最上位のディレクトリツリーと同じファイルシステム上に存在する必要があるため)。また、"lowerdir=" マウントオプションはこのスイッチと逆の順番で積み重ねるパスを受け取ります。

-E NAME=VALUE, --setenv=NAME=VALUE

コンテナの init プロセスに指定する環境変数を "NAME=VALUE" という形式で指定します。デフォルトの変数を上書きしたり変数を追加することができます。このパラメータは複数回使えます。

--register=

systemd-machined(8) でコンテナを登録するかどうか制御します。論理値を指定し、デフォルトは "yes" です。コンテナで完全なオペレーティングシステムを実行 (システムとサービスマネージャを PID 1 で実行) する必要がある場合、このオプションを有効にするべきです。machinectl(1) でコンテナにアクセスできるようになり ps(1) などのツールで表示されるようになります。コンテナでサービスマネージャを動作させない場合、このオプションは "no" に設定することを推奨します。

--keep-unit

コンテナを実行する一時的なスコープユニットを作成するかわりに、systemd-nspawn を呼び出したサービスまたはスコープユニットを使用します。--register=yes が設定された場合、このユニットは systemd-machined(8) で登録されます。サービスユニットの中から systemd-nspawn を呼び出すときはこのスイッチを使用するべきで、サービスユニットは systemd-nspawn コンテナをひとつ実行するだけにしたほうが良いでしょう。このオプションはユーザーセッションから実行されたときは利用できません。

--keep-unit を指定すると --slice= と --property= の効果が無効になるので注意してください。--keep-unit と --register=no を組み合わせると systemd-machined によるユニットの割当や登録が全て無効になります。

--personality=

コンテナの uname(2) で報告されるアーキテクチャ ("personality") を制御します。現在、"x86" と "x86-64" のみサポートされています。62ビットのホストで32ビットのコンテナを実行する場合に有用です。この設定を使用しない場合、コンテナで認識されるパーソナリティはホストと同じになります。

-q, --quiet

ツールによる状態の出力をオフにします。このスイッチを使用した場合、nspawn からの出力はコンテナ OS のコンソールの出力だけになります。

--volatile, --volatile=MODE

コンテナを volatile モードで起動します。mode パラメータが指定されなかった場合や mode に yes を指定した場合、フル volatile モードが有効になります。ルートディレクトリがほとんど何もない無人島状態の "tmpfs" インスタンスとしてマウントされ、OS ツリーの /usr は読み取り専用モードでマウントされます (システムは読み取り専用の OS イメージで初期状態・初期設定で起動し、変更は全てシャットダウン時に消失します)。mode パラメータに state と指定した場合、OS ツリーは読み取り専用でマウントされますが、/var は "tmpfs" インスタンスとしてマウントされます (システムは読み取り専用の OS リソースと設定で初期状態から起動し、後者の変更はシャットダウン時に全て失われます)。mode パラメータに no と指定した場合 (デフォルト)、OS ツリーは書き込み可能になります。

このオプションはホスト環境における "systemd.volatile=" カーネルコマンドラインスイッチと同じような機能を提供します。詳しくは kernel-command-line(7) を参照してください。

この設定を有効にしても問題なく動作するコンテナのオペレーティングシステムは /usr だけしかマウントされていなくても起動して、自動的に /var を作成することができ、さらに "--volatile=yes" の場合は /etc も自動生成するようになってなければなりません。

--settings=MODE

systemd-nspawn で .nspawn ファイルを検索してコンテナ別の設定を使用するかどうか制御します。論理値か特殊な値として override または trusted で指定します。

有効にした場合 (デフォルト)、マシンと同じ名前 (--machine= で指定した名前かディレクトリやイメージファイルの名前から取得される) の拡張子が .nspawn の設定ファイルを /etc/systemd/nspawn/ と /run/systemd/nspawn/ から検索します。ファイルが見つかった場合、設定が読み込まれて使用されます。ファイルが見つからなかった場合、イメージファイルと同じディレクトリあるいはコンテナのルートディレクトリの親ディレクトリも検索されます。ファイルが見つかったら同じく設定が読み込まれて使用されますが、潜在的に危険な設定は無視されます。どちらの場合でも、.nspawn ファイルからロードされた設定よりもコマンドラインで指定した設定のほうが優先されます。コンテナの権限を格上げしたりホストのファイルやディレクトリなどのリソースにアクセスする権限を与える設定は危険な設定とみなされます。.nspawn ファイルのフォーマットと中身について詳しくは systemd.nspawn(5) を参照してください。

このオプションを override に設定した場合、同じようにファイルが検索され読み込まれますが、優先順位が逆になります: .nspawn ファイルの設定のほうがコマンドラインオプションよりも優先されます。

このオプションを trusted に設定した場合、同じようにファイルが検索され読み込まれますが、ファイルが /etc/systemd/nspawn/ や /run/systemd/nspawn/、あるいはイメージファイルと同じディレクトリやコンテナのルートディレクトリのどこにあったかは関係なく、全ての設定が適用されます。ただし、コマンドライン引数がファイルの設定よりも優先されるのは変わりません。

無効にした場合、.nspawn ファイルは読み込まれずコマンドラインで指定した設定だけが適用されます。

--notify-ready=

コンテナの init プロセスからの通知のサポートを設定します。--notify-ready= では論理値を指定します (no と yes)。このオプションを no にすると systemd-nspawn は init プロセスが作成されたときに systemd に "READY=1" メッセージを通知します。このオプションを yes にすると systemd-nspawn はコンテナの init プロセスからの "READY=1" メッセージを待機してから systemd に送信します。通知について詳しくは sd_notify(3) を参照。

-h, --help

短いヘルプテキストを表示して終了。

--version

短いバージョン文字列を表示して終了。

サンプル

例 1. Fedora のイメージをダウンロードしてシェルを起動

# machinectl pull-raw --verify=no \
      https://download.fedoraproject.org/pub/fedora/linux/releases/25/CloudImages/x86_64/images/Fedora-Cloud-Base-25-1.3.x86_64.raw.xz
# systemd-nspawn -M Fedora-Cloud-Base-25-1.3.x86_64.raw

上記のコマンドは machinectl(1) を使ってイメージをダウンロードしてシェルを開きます。

例 2. コンテナの中に最小限の Fedora ディストリビューションをビルド・起動

# dnf -y --releasever=27 --installroot=/var/lib/machines/f27container \
      --disablerepo='*' --enablerepo=fedora --enablerepo=updates install \
      systemd passwd dnf fedora-release vim-minimal
# systemd-nspawn -bD /var/lib/machines/f27container

上記のコマンドは /var/lib/machines/f27container ディレクトリに最小限の Fedora 5 環境をインストールして名前空間コンテナを使って OS を起動します。インストール先が標準の /var/lib/machines/ ディレクトリの下になっているため、systemd-nspawn -M f27container でマシンを起動できます。

例 3. 最小限の Debian unstable ディストリビューションのコンテナでシェルを生成

# debootstrap unstable ~/debian-tree/
# systemd-nspawn -D ~/debian-tree/

上記のコマンドは ~/debian-tree/ ディレクトリに最小限の Debian unstable ディストリビューションをインストールして名前空間コンテナを使ってシェルを起動します。

debootstrap は Debian 6, Ubuntu 7, Tanglu 8 をサポートしているため、同じコマンドを使ってこれらのディストリビューションをインストールできます。Debian ファミリーの他のディストリビューションについては、ミラーを指定する必要があります。debootstrap(8) を参照してください。

例 4. コンテナで最小限の Arch Linux ディストリビューションを起動

# pacstrap -c -d ~/arch-tree/ base
# systemd-nspawn -bD ~/arch-tree/

上記のコマンドは ~/arch-tree/ ディレクトリに最小限の Arch Linux 9 ディストリビューションをインストールして名前空間コンテナを使って OS を起動します。

例 5. OpenSUSE Tumbleweed ローリングディストリビューションをインストール

# zypper --root=/var/lib/machines/tumbleweed ar -c \
      https://download.opensuse.org/tumbleweed/repo/oss tumbleweed
# zypper --root=/var/lib/machines/tumbleweed refresh
# zypper --root=/var/lib/machines/tumbleweed install --no-recommends \
      systemd shadow zypper openSUSE-release vim
# systemd-nspawn -M tumbleweed passwd root
# systemd-nspawn -M tumbleweed -b

OpenSUSE 10 を参照。

例 6. ホスト環境の一時的なスナップショットを起動

# systemd-nspawn -D / -xb

上記のコマンドはホスト環境のスナップショットコピーを起動します。コンテナの終了時にコピーはすぐに消去されます。コンテナの実行時にファイルシステムに変更を行っても全てシャットダウン時に消失します。

例 7. SELinux サンドボックスセキュリティコンテキストでコンテナを起動

# chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
# systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 \
      -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh

例 8. OSTree でコンテナを起動

# systemd-nspawn -b -i ~/image.raw \
      --pivot-root=/ostree/deploy/$OS/deploy/$CHECKSUM:/sysroot \
      --bind=+/sysroot/ostree/deploy/$OS/var:/var

終了ステータス

コンテナの中で実行されたプログラムの終了コードが返ります。