Ubuntu Manpage: guestfish - ゲスト・ファイルシステム・シェル

Provided by: guestfish_1.46.2-10ubuntu3_amd64

名前

       guestfish - ゲスト・ファイルシステム・シェル

書式

        guestfish [--options] [commands]

        guestfish

        guestfish [--ro|--rw] -a disk.img

        guestfish [--ro|--rw] -a disk.img -m dev[:mountpoint]

        guestfish -d libvirt-domain

        guestfish [--ro|--rw] -a disk.img -i

        guestfish -d libvirt-domain -i

説明

       guestfish は仮想マシンのファイルシステムを検査および変更するために 使用するシェルおよびコ
       マンドラインツールです。 これは libguestfs を使用し、 guestfs API のすべての機能を提供しま
       す。 詳細は guestfs(3) を参照してください。

       guestfish は、シェルスクリプト、コマンドライン、対話式シェルから libguestfs API への構造的
       なアクセスを提供します。 壊れた仮想マシンイメージを救出したい場合、 virt-rescue(1) コマン
       ドを考えてください。

例

   対話式シェルとして
        $ guestfish

       guestfish へようこそ。仮想マシンのファイルシステムを 編集するためのゲスト・ファイルシステ
       ム・シェルです。
        入力: コマンド一覧の表示は 'help'
              マニュアルの参照は 'man'
              シェルの終了は 'quit'

        ><fs> add-ro disk.img
        ><fs> run
        ><fs> list-filesystems
        /dev/sda1: ext4
        /dev/vg_guest/lv_root: ext4
        /dev/vg_guest/lv_swap: swap
        ><fs> mount /dev/vg_guest/lv_root /
        ><fs> cat /etc/fstab
        # /etc/fstab
        # Created by anaconda
        [...]
        ><fs> exit

   シェルスクリプトから
       Create a new /etc/motd file in a guest or disk image:

        guestfish <<_EOF_
        add disk.img
        run
        mount /dev/vg_guest/lv_root /
        write /etc/motd "Welcome, new users"
        _EOF_

       ディスクイメージにある LVM 論理ボリュームを一覧表示します:

        guestfish -a disk.img --ro <<_EOF_
        run
        lvs
        _EOF_

       ディスクイメージにあるファイルシステムをすべて一覧表示します:

        guestfish -a disk.img --ro <<_EOF_
        run
        list-filesystems
        _EOF_

   コマンドライン 1 行において
       Update /etc/resolv.conf in a guest:

        guestfish \
          add disk.img : run : mount /dev/vg_guest/lv_root / : \
          write /etc/resolv.conf "nameserver 1.2.3.4"

       Edit /boot/grub/grub.conf interactively:

        guestfish --rw --add disk.img \
          --mount /dev/vg_guest/lv_root \
          --mount /dev/sda1:/boot \
          edit /boot/grub/grub.conf

   ディスクを自動的にマウントします
       仮想マシンからディスクを自動的にマウントするには -i オプションを使用します:

        guestfish --ro -a disk.img -i cat /etc/group

        guestfish --ro -d libvirt-domain -i cat /etc/group

       Another way to edit /boot/grub/grub.conf interactively is:

        guestfish --rw -a disk.img -i edit /boot/grub/grub.conf

   スクリプトのインタープリターとして
       ext2 フォーマット済みパーティションを含む 100MB ディスクを作成します:

        #!/usr/bin/guestfish -f
        sparse test1.img 100M
        run
        part-disk /dev/sda mbr
        mkfs ext2 /dev/sda1

   準備済みディスクを用いた起動
       Create a 1G disk called test1.img containing a single ext2-formatted partition:

        guestfish -N fs

       利用可能なものを一覧表示する方法:

        guestfish -N help | less

   リモートドライブ
       SSH を使用してリモートディスクにアクセスします:

        guestfish -a ssh://example.com/path/to/disk.img

   リモート制御
        eval "`guestfish --listen`"
        guestfish --remote add-ro disk.img
        guestfish --remote run
        guestfish --remote lvs

オプション

       --help
           オプションの一般的なヘルプを表示します。

       -h
       --cmd-help
           すべての利用可能な guestfish コマンドを一覧表示します。

       -h CMD
       --cmd-help CMD
           単一のコマンド "cmd" の詳細なヘルプを表示します。

       -a IMAGE
       --add IMAGE
           ブロックデバイスまたは仮想マシンイメージをシェルに追加します。

           ディスクイメージの形式は自動検知されます。 これを上書きして強制的に特定の形式を使用す
           る場合、 --format=.. オプションを使用します。

           このフラグを使用することは "add" コマンドを使用することとほぼ同じです。 --ro フラグが
           指定された場合、"readonly:true" と同じです。 --format=...  フラグが指定された場
           合、"format:..." と同じです。

       -a URI
       --add URI
           リモートディスクを追加します。 "リモートストレージの追加" 参照。

       --blocksize=512
       --blocksize=4096
       --blocksize
           This parameter sets the sector size of the disk image.  It affects all explicitly
           added subsequent disks after this parameter.  Using --blocksize with no argument
           switches the disk sector size to the default value which is usually 512 bytes.  See
           also "guestfs_add_drive_opts" in guestfs(3).

       -c URI
       --connect URI
            I<-d> オプションと同時に使用するとき、 これは使用する libvirt URI を指定します。 標準状態で標準の libvirt
           接続を使用します。

       --csh
           --listen オプションと csh 系シェルを使用している場合、 このオプションを使用します。 以
           下の "リモート制御と csh" のセクションを参照してください。

       -d LIBVIRT-DOMAIN
       --domain LIBVIRT-DOMAIN
           名前付き libvirt 仮想マシンからディスクを追加します。 --ro オプションも使用されている
           場合、すべての libvirt 仮想マシンを使用できます。 しかしながら、書き込みモードでは、
           停止状態の libvirt 仮想マシンのみ指定できます。

           名前の代わりに仮想マシンの UUID を使用できます。

           このフラグを使用することは、"add-domain" コマンドを使用することとほぼ同等です。 --ro
           フラグを指定した場合、"readonly:true" が付きます。 --format=... フラグを指定した場
           合、"format:..."  が付きます。

       --echo-keys
           キーやパスフレーズを入力するとき、通常 guestfish はエコーを無効化します。 そのため、入
           力内容を確認できません。 テンペスト攻撃の心配がなく、 部屋に誰も居なければ、 入力内容
           を確認するためにこのフラグを指定できます。

       -f FILE
       --file FILE
           Read commands from "FILE".  To write pure guestfish scripts, use:

            #!/usr/bin/guestfish -f

       --format=raw|qcow2|..
       --format
           -a オプションは標準状態でディスクイメージの形式を自動検知します。 これを使用することに
           より、コマンドラインで後続の -a オプションのディスク形式を強制的に指定できます。 引数
           なしで --format を使用することにより、 後続の -a オプションに対して自動検知に戻せま
           す。

           例:

            guestfish --format=raw -a disk.img

           forces raw format (no auto-detection) for disk.img.

            guestfish --format=raw -a disk.img --format -a another.img

           forces raw format (no auto-detection) for disk.img and reverts to auto-detection for
           another.img.

           仮想マシンのディスクイメージが信頼できない raw 形式である場合、 ディスク形式を指定する
           ためにこのオプションを使用すべきです。 これにより、悪意のある仮想マシンにより起こり得
           る セキュリティ問題を回避できます (CVE-2010-3851)。 "add" 参照。

       -i
       --inspector
           virt-inspector(1) コードを使用すると、 オペレーティングシステムを判定するためにディス
           クを検査します。 また、実際の仮想マシンにマウントすることと同じように ファイルシステム
           をマウントします。

           一般的な使用法は次のどちらかです:

            guestfish -d myguest -i

           (myguest という停止状態の libvirt 仮想マシンの場合)、または:

            guestfish --ro -d myguest -i

           (動作中の仮想マシンの場合、読み込み専用)、 またはブロックデバイスを直接指定します:

            guestfish --rw -a /dev/Guests/MyGuest -i

           コマンドライン構文が古いバージョンの guestfish から少し変更されたことに注意してくださ
           い。 まだ古い構文を使用することができます:

            guestfish [--ro] -i disk.img

            guestfish [--ro] -i libvirt-domain

           このフラグを使用することは、 "inspect-os" コマンドを使用することとほぼ同じです。 検出
           されたファイルシステムをマウントするために 他のコマンドを使用します。

       --key SELECTOR
           Specify a key for LUKS, to automatically open a LUKS device when using the inspection.
           "ID" can be either the libguestfs device name, or the UUID of the LUKS device.

           --key "ID":key:KEY_STRING
               Use the specified "KEY_STRING" as passphrase.

           --key "ID":file:FILENAME
               Read the passphrase from FILENAME.

       --keys-from-stdin
           Read key or passphrase parameters from stdin.  The default is to try to read
           passphrases from the user by opening /dev/tty.

           If there are multiple encrypted devices then you may need to supply multiple keys on
           stdin, one per line.

       --listen
           バックグラウンドにフォークし、リモートコマンドをリッスンします。 以下の "REMOTE
           CONTROL GUESTFISH OVER A SOCKET" 参照。

       --live
           動作中の仮想マシンに接続します。 (実験的、"ATTACHING TO RUNNING DAEMONS" in guestfs(3)
           参照)。

       -m dev[:mountpoint[:options[:fstype]]]
       --mount dev[:mountpoint[:options[:fstype]]]
           指定されたマウントポイントにある、 名前付きパーティションまたは論理ボリュームをマウン
           トします。

           If the mountpoint is omitted, it defaults to /.

           You have to mount something on / before most commands will work.

           何らかの -m または --mount オプションが指定されると、 仮想マシンが自動的に起動されま
           す。

           If you don’t know what filesystems a disk image contains, you can either run guestfish
           without this option, then list the partitions, filesystems and LVs available (see
           "list-partitions", "list-filesystems" and "lvs" commands), or you can use the
           virt-filesystems(1) program.

           マウントパラメーターの三番目の (ほとんど使用されない) 項目は、 バックエンドのファイル
           システムをマウントするために使用される マウントオプションの一覧です。 これが指定されて
           いない場合、 マウントオプションは空文字列または "ro" (--ro フラグが使用されている場合)
           になります。

            -m /dev/sda1:/:acl,user_xattr

           このフラグを使用することは、 "mount-options" コマンドを使用することと同等です。

           パラメーターの四番目の項目は使用するファイルシステムドライバー ("ext3" や "ntfs" など)
           です。 これはほとんど必要ありません。 しかし、複数のドライバーがファイルシステムに対し
           て有効である場合 (例: "ext2" と "ext3")、 または libguestfs がファイルシステムを誤検知
           している場合、 これは有用です。

       --network
           仮想マシンにおいて QEMU のユーザーモードのネットワークを有効にします。

       -N [FILENAME=]TYPE
       --new [FILENAME=]TYPE
       -N help
           Prepare a fresh disk image formatted as "TYPE".  This is an alternative to the -a
           option: whereas -a adds an existing disk, -N creates a preformatted disk with a
           filesystem and adds it.  See "PREPARED DISK IMAGES" below.

       -n
       --no-sync
           自動同期を無効化します。 これは標準で有効化されています。 guestfs(3) マニュアルページ
           の自動同期に関する記載を 参照してください。

       --no-dest-paths
           Don’t tab-complete paths on the guest filesystem.  It is useful to be able to hit the
           tab key to complete paths on the guest filesystem, but this causes extra "hidden"
           guestfs calls to be made, so this option is here to allow this feature to be disabled.

       --pipe-error
           コマンドのパイプ (以下の "パイプ" 参照) への書き込みに失敗した場合、 このコマンドがエ
           ラーを返します。

           標準状態では、(歴史的な理由から) そのようなエラーは次のために無視されます。

            ><fs> command_with_lots_of_output | head

           エラーは渡されません。

       --progress-bars
           guestfish が非対話式モードを使用している場合でも、 進行状況バーを有効にします。

           guestfish を対話式シェルで使用するとき、 進行状況バーが標準で有効になっています。

       --no-progress-bars
           進行状況バーを無効にします。

       --remote
       --remote=PID
           リモートコマンドを $GUESTFISH_PID または "pid" に送信します。 以下の "REMOTE CONTROL
           GUESTFISH OVER A SOCKET" 参照。

       -r
       --ro
           ディスクが追加され、読み込み専用でマウントされるよう、 -a, -d, -m オプションを変更しま
           す。

           ディスクイメージまたは仮想マシンが使用中の場合、 必ずこのオプションを使用する必要があ
           ります。 また、ディスクへの書き込みアクセスが不要な場合、 このオプションが一般的に推奨
           されます。

           -N オプションで作成された準備済みディスクイメージは、 このオプションの効果がないことに
           注意してください。 "add" のようなコマンドも影響を受けません。 必要があれ
           ば、"readonly:true" オプションを明示的に指定する必要があります。

           以下の "OPENING DISKS FOR READ AND WRITE" 参照。

       --selinux
           This option is provided for backwards compatibility and does nothing.

       -v
       --verbose
           非常に冗長なメッセージを出力します。  バグを探す場合、とくに有用です。

       -V
       --version
           guestfish / libguestfs のバージョン番号を表示して、終了します。

       -w
       --rw
           ディスクが追加され、読み書き可能でマウントされるよう、 -a, -d, -m オプションを変更しま
           す。

           以下の "OPENING DISKS FOR READ AND WRITE" 参照。

       -x  各コマンドを実行する前にエコーします。

コマンドラインにおけるコマンド

       Any additional (non-option) arguments are treated as commands to execute.

       Commands to execute should be separated by a colon (":"), where the colon is a separate
       parameter.  Thus:

        guestfish cmd [args...] : cmd [args...] : cmd [args...] ...

       If there are no additional arguments, then we enter a shell, either an interactive shell
       with a prompt (if the input is a terminal) or a non-interactive shell.

       In either command line mode or non-interactive shell, the first command that gives an
       error causes the whole shell to exit.  In interactive mode (with a prompt) if a command
       fails, you can continue to enter commands.

       Note that arguments of the commands will be considered as guestfish options if they start
       with a dash ("-"): you can always separate the guestfish options and the rest of the
       commands (with their arguments)  using a double dash ("--").  For example:

        guestfish -- disk_create overlay.qcow2 qcow2 -1 backingfile:image.img

launch (または run) の使用法

       As with guestfs(3), you must first configure your guest by adding disks, then launch it,
       then mount any disks you need, and finally issue actions/commands.  So the general order
       of the day is:

       •   add or -a/--add

       •   launch (別名 run)

       •   mount または -m/--mount

       •   any other commands

       "run" is a synonym for "launch".  You must "launch" (or "run")  your guest before mounting
       or performing any other commands.

       The only exception is that if any of the -i, -m, --mount, -N or --new options were given
       then "run" is done automatically, simply because guestfish can't perform the action you
       asked for without doing this.

OPENING DISKS FOR READ AND WRITE

       The guestfish, guestmount(1) and virt-rescue(1) options --ro and --rw affect whether the
       other command line options -a, -c, -d, -i and -m open disk images read-only or for
       writing.

       In libguestfs ≤ 1.10, guestfish, guestmount and virt-rescue defaulted to opening disk
       images supplied on the command line for write.  To open a disk image read-only you have to
       do -a image --ro.

       This matters: If you accidentally open a live VM disk image writable then you will cause
       irreversible disk corruption.

       In a future libguestfs we intend to change the default the other way.  Disk images will be
       opened read-only.  You will have to either specify guestfish --rw, guestmount --rw, virt-
       rescue --rw, or change the configuration file in order to get write access for disk images
       specified by those other command line options.

       This version of guestfish, guestmount and virt-rescue has a --rw option which does nothing
       (it is already the default).  However it is highly recommended that you use this option to
       indicate that you need write access, and prepare your scripts for the day when this option
       will be required for write access.

       Note: This does not affect commands like "add" and "mount", or any other libguestfs
       program apart from guestfish and guestmount.

QUOTING

       You can quote ordinary parameters using either single or double quotes.  For example:

        add "file with a space.img"

        rm '/file name'

        rm '/"'

       A few commands require a list of strings to be passed.  For these, use a whitespace-
       separated list, enclosed in quotes.  Strings containing whitespace to be passed through
       must be enclosed in single quotes.  A literal single quote must be escaped with a
       backslash.

        vgcreate VG "/dev/sda1 /dev/sdb1"
        command "/bin/echo 'foo      bar'"
        command "/bin/echo \'foo\'"

   ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
       In double-quoted arguments (only) use backslash to insert special characters:

       "\a"
           アラート（ベル）文字。

       "\b"
           バックスペース文字。

       "\f"
           フォームフィード文字。

       "\n"
           改行文字。

       "\r"
           復帰文字。

       "\t"
           水平タブ文字。

       "\v"
           垂直タブ文字。

       "\""
           二重引用符文字。

       "\ooo"
           8 進値 ooo を持つ文字。（C とは異なり）ちょうど 3 桁である必要があります。

       "\xhh"
           16 進数値 hh を持つ文字。ちょうど 2 桁である必要があります。

           In the current implementation "\000" and "\x00" cannot be used in strings.

       "\\"
           文字としてのバックスラッシュ文字。

オプション引数

       Some commands take optional arguments.  These arguments appear in this documentation as
       "[argname:..]".  You can use them as in these examples:

        add filename

        add filename readonly:true

        add filename format:qcow2 readonly:false

       Each optional argument can appear at most once.  All optional arguments must appear after
       the required ones.

数値

       このセクションはパラメーターとして整数を取り得るすべてのコマンドに適用されます。

   容量の接尾辞
       コマンドがバイト単位で計算されるパラメーターをとるとき、キロバイト、メガバイト、それより大
       きい容量を指定するために、以下の接尾辞のどれかをとることができます:

       k または K または KiB
           キロ（1024 の掛け算）バイト単位の容量です。

       KB  国際単位系（SI）の 1000 バイト単位の容量です。

       M または MiB
           メガ（1048576 の掛け算）バイト単位の容量です。

       MB  国際単位系（SI）の 1000000 バイト単位の容量です。

       G または GiB
           ギガ（2 の 30 乗の掛け算）バイト単位の容量です。

       GB  国際単位系（SI）の 10 の 9 乗バイト単位の容量です。

       T または TiB
           テラ（2 の 40 乗の掛け算）バイト単位の容量です。

       TB  国際単位系（SI）の 10 の 12 乗バイト単位の容量です。

       P または PiB
           ペタ（2 の 50 乗の掛け算）バイト単位の容量です。

       PB  国際単位系（SI）の 10 の 15 乗バイト単位の容量です。

       E または EiB
           エクサ（2 の 60 乗の掛け算）バイト単位の容量です。

       EB  国際単位系（SI）の 10 の 18 乗バイト単位の容量です。

       Z または ZiB
           ゼタ（2 の 70 乗の掛け算）バイト単位の容量です。

       ZB  国際単位系（SI）の 10 の 21 乗バイト単位の容量です。

       Y または YiB
           ヨタ（2 の 80 乗の掛け算）バイト単位の容量です。

       YB  国際単位系（SI）の 10 の 24 乗バイト単位の容量です。

       例:

        truncate-size /file 1G

       ファイルを 1 ギガバイトに切り詰めます。

       いくつかのコマンドはキロバイトまたはメガバイト単位の容量をとるので注意してください (たとえ
       ば、"memsize" のパラメーターはすでにメガバイト単位で指定されています)。接尾辞をつけること
       により、期待しない結果になることがあります。

   10 進数値および 16 進数値
       For specifying the radix (base) use the C convention: 0 to prefix an octal number or "0x"
       to prefix a hexadecimal number.  For example:

        1234      10 進数 1234
        02322     8 進数、10 進数の 1234
        0x4d2     16 進数、10 進数の 1234

       When using the "chmod" command, you almost always want to specify an octal number for the
       mode, and you must prefix it with 0 (unlike the Unix chmod(1) program):

        chmod 0777 /public  # 正解
        chmod 777 /public   # 誤り! このモードは 10 進 777 = 8 進 01411 です。

       Commands that return numbers usually print them in decimal, but some commands print
       numbers in other radices (eg. "umask" prints the mode in octal, preceded by 0).

ワイルドカードおよびグロブ

       Neither guestfish nor the underlying guestfs API performs wildcard expansion (globbing) by
       default.  So for example the following will not do what you expect:

        rm-rf /home/*

       Assuming you don’t have a directory called literally /home/* then the above command will
       return an error.

       ワイルドカードの展開を実行するには "glob" コマンドを使用します。

        glob rm-rf /home/*

       runs "rm-rf" on each path that matches (ie. potentially running the command many times),
       equivalent to:

        rm-rf /home/jim
        rm-rf /home/joe
        rm-rf /home/mary

       "glob" only works on simple guest paths and not on device names.

       If you have several parameters, each containing a wildcard, then glob will perform a
       Cartesian product.

       Any line which starts with a # character is treated as a comment and ignored.  The # can
       optionally be preceded by whitespace, but not by a command.  For example:

        # これはコメントです
                # これはコメントです
        foo # コメントではありません

       空行も無視されます。

ローカルのコマンドの実行法

Any line which starts with a ! character is treated as a command sent to the local shell
(/bin/sh or whatever system(3) uses). For example:

!mkdir local
tgz-out /remote local/remote-data.tar.gz

will create a directory "local" on the host, and then export the contents of /remote on
the mounted filesystem to local/remote-data.tar.gz. (See "tgz-out").

To change the local directory, use the "lcd" command. "!cd" will have no effect, due to
the way that subprocesses work in Unix.

LOCAL COMMANDS WITH INLINE EXECUTION
If a line starts with <! then the shell command is executed (as for !), but subsequently
any output (stdout) of the shell command is parsed and executed as guestfish commands.

Thus you can use shell script to construct arbitrary guestfish commands which are then
parsed by guestfish.

For example it is tedious to create a sequence of files (eg. /foo.1 through /foo.100)
using guestfish commands alone. However this is simple if we use a shell script to create
the guestfish commands for us:

<! for n in `seq 1 100`; do echo write /foo.$n $n; done

or with names like /foo.001:

<! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done

When using guestfish interactively it can be helpful to just run the shell script first
(ie. remove the initial "<" character so it is just an ordinary ! local command), see what
guestfish commands it would run, and when you are happy with those prepend the "<"
character to run the guestfish commands for real.

パイプ

       Use "command <space> | command" to pipe the output of the first command (a guestfish
       command) to the second command (any host command).  For example:

        cat /etc/passwd | awk -F: '$3 == 0 { print }'

       (where "cat" is the guestfish cat command, but "awk" is the host awk program).  The above
       command would list all accounts in the guest filesystem which have UID 0, ie. root
       accounts including backdoors.  Other examples:

        hexdump /bin/ls | head
        list-devices | tail -1
        tgz-out / - | tar ztf -

       The space before the pipe symbol is required, any space after the pipe symbol is optional.
       Everything after the pipe symbol is just passed straight to the host shell, so it can
       contain redirections, globs and anything else that makes sense on the host side.

       To use a literal argument which begins with a pipe symbol, you have to quote it, eg:

        echo "|"

ホームディレクトリ

       If a parameter starts with the character "~" then the tilde may be expanded as a home
       directory path (either "~" for the current user's home directory, or "~user" for another
       user).

       Note that home directory expansion happens for users known on the host, not in the guest
       filesystem.

       To use a literal argument which begins with a tilde, you have to quote it, eg:

        echo "~"

暗号化ディスク

       Libguestfs has some support for Linux guests encrypted according to the Linux Unified Key
       Setup (LUKS) standard, which includes nearly all whole disk encryption systems used by
       modern Linux guests, and Windows BitLocker.

       Identify encrypted block devices and partitions using "vfs-type":

        ><fs> vfs-type /dev/sda2
        crypto_LUKS

       または:

        ><fs> vfs-type /dev/sda2
        BitLocker

       Then open those devices using "cryptsetup-open".  This creates a device-mapper device
       called /dev/mapper/name.

        ><fs> cryptsetup-open /dev/sda2 name
        Enter key or passphrase ("key"): <enter the passphrase>

       For Linux guests you have to tell LVM to scan for volume groups on the newly created
       mapper device:

        vgscan
        vg-activate-all true

       The filesystems or logical volumes can now be mounted in the usual way.

       Before closing an encrypted device you must unmount any logical volumes on it and
       deactivate the volume groups by calling "vg-activate false VG" on each one.  Then you can
       close the mapper device:

        vg-activate false /dev/VG
        cryptsetup-close /dev/mapper/name

Windows のパス

       If a path is prefixed with "win:" then you can use Windows-style drive letters and paths
       (with some limitations).  The following commands are equivalent:

        file /WINDOWS/system32/config/system.LOG

        file win:\windows\system32\config\system.log

        file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG

       The parameter is rewritten "behind the scenes" by looking up the position where the drive
       is mounted, prepending that to the path, changing all backslash characters to forward
       slash, then resolving the result using "case-sensitive-path".  For example if the E: drive
       was mounted on /e then the parameter might be rewritten like this:

        win:e:\foo\bar => /e/FOO/bar

       This only works in argument positions that expect a path.

ファイルのアップロード方法およびダウンロード方法

       For commands such as "upload", "download", "tar-in", "tar-out" and others which upload
       from or download to a local file, you can use the special filename "-" to mean "from
       stdin" or "to stdout".  For example:

        upload - /foo

       reads stdin and creates from that a file /foo in the disk image, and:

        tar-out /etc - | tar tf -

       writes the tarball to stdout and then pipes that into the external "tar" command (see
       "PIPES").

       When using "-" to read from stdin, the input is read up to the end of stdin.  You can also
       use a special "heredoc"-like syntax to read up to some arbitrary end marker:

        upload -<<END /foo
        input line 1
        input line 2
        input line 3
        END

       Any string of characters can be used instead of "END".  The end marker must appear on a
       line of its own, without any preceding or following characters (not even spaces).

       Note that the "-<<" syntax only applies to parameters used to upload local files (so-
       called "FileIn" parameters in the generator).

EXIT ON ERROR BEHAVIOUR

       By default, guestfish will ignore any errors when in interactive mode (ie. taking commands
       from a human over a tty), and will exit on the first error in non-interactive mode
       (scripts, commands given on the command line).

       If you prefix a command with a - character, then that command will not cause guestfish to
       exit, even if that (one) command returns an error.

guestfish のソケット経由のリモート制御

       Guestfish can be remote-controlled over a socket.  This is useful particularly in shell
       scripts where you want to make several different changes to a filesystem, but you don't
       want the overhead of starting up a guestfish process each time.

       Start a guestfish server process using:

        eval "`guestfish --listen`"

       and then send it commands by doing:

        guestfish --remote cmd [...]

       To cause the server to exit, send it the exit command:

        guestfish --remote exit

       Note that the server will normally exit if there is an error in a command.  You can change
       this in the usual way.  See section "EXIT ON ERROR BEHAVIOUR".

   CONTROLLING MULTIPLE GUESTFISH PROCESSES
       The "eval" statement sets the environment variable $GUESTFISH_PID, which is how the
       --remote option knows where to send the commands.  You can have several guestfish listener
       processes running using:

        eval "`guestfish --listen`"
        pid1=$GUESTFISH_PID
        eval "`guestfish --listen`"
        pid2=$GUESTFISH_PID
        ...
        guestfish --remote=$pid1 cmd
        guestfish --remote=$pid2 cmd

   REMOTE CONTROL AND CSH
       csh 系のシェル (csh, tcsh など) を使用するとき、--csh オプションを追加する必要があります:

        eval "`guestfish --listen --csh`"

   リモート制御の詳細
       Remote control happens over a Unix domain socket called /tmp/.guestfish-$UID/socket-$PID,
       where $UID is the effective user ID of the process, and $PID is the process ID of the
       server.

       Guestfish client and server versions must match exactly.

       Older versions of guestfish were vulnerable to CVE-2013-4419 (see "CVE-2013-4419" in
       guestfs(3)).  This is fixed in the current version.

   USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
       From Bash, you can use the following code which creates a guestfish instance, correctly
       quotes the command line, handles failure to start, and cleans up guestfish when the script
       exits:

        #!/bin/bash -

        set -e

        guestfish[0]="guestfish"
        guestfish[1]="--listen"
        guestfish[2]="--ro"
        guestfish[3]="-a"
        guestfish[4]="disk.img"

        GUESTFISH_PID=
        eval $("${guestfish[@]}")
        if [ -z "$GUESTFISH_PID" ]; then
            echo "error: guestfish didn't start up, see error messages above"
            exit 1
        fi

        cleanup_guestfish ()
        {
            guestfish --remote -- exit >/dev/null 2>&1 ||:
        }
        trap cleanup_guestfish EXIT ERR

        guestfish --remote -- run

        # ...

   REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS
       Options such as -a, --add, -N, --new etc don’t interact properly with remote support.
       They are processed locally, and not sent through to the remote guestfish.  In particular
       this won't do what you expect:

        guestfish --remote --add disk.img

       Don’t use these options.  Use the equivalent commands instead, eg:

        guestfish --remote add-drive disk.img

       または:

        guestfish --remote
        ><fs> add disk.img

   REMOTE CONTROL RUN COMMAND HANGING
       Using the "run" (or "launch") command remotely in a command substitution context hangs,
       ie. don't do (note the backquotes):

        a=`guestfish --remote run`

       Since the "run" command produces no output on stdout, this is not useful anyway.  For
       further information see https://bugzilla.redhat.com/show_bug.cgi?id=592910.

PREPARED DISK IMAGES

       Use the -N [filename=]type or --new [filename=]type parameter to select one of a set of
       preformatted disk images that guestfish can make for you to save typing.  This is
       particularly useful for testing purposes.  This option is used instead of the -a option,
       and like -a can appear multiple times (and can be mixed with -a).

       The new disk is called test1.img for the first -N, test2.img for the second and so on.
       Existing files in the current directory are overwritten.  You can use a different filename
       by specifying "filename=" before the type (see examples below).

       The type briefly describes how the disk should be sized, partitioned, how filesystem(s)
       should be created, and how content should be added.  Optionally the type can be followed
       by extra parameters, separated by ":" (colon) characters.  For example, -N fs creates a
       default 1G, sparsely-allocated disk, containing a single partition, with the partition
       formatted as ext2.  -N fs:ext4:2G is the same, but for an ext4 filesystem on a 2GB disk
       instead.

       Note that the prepared filesystem is not mounted.  You would usually have to use the
       "mount /dev/sda1 /" command or add the -m /dev/sda1 option.

       If any -N or --new options are given, the libguestfs appliance is automatically launched.

   例
       Create a 1G disk with an ext4-formatted partition, called test1.img in the current
       directory:

        guestfish -N fs:ext4

       VFAT フォーマットのパーティションを持つ 32MB ディスクを作成して、マウントします:

        guestfish -N fs:vfat:32M -m /dev/sda1

       200MB の空ディスクを作成します:

        guestfish -N disk:200M

       Create a blank 200MB disk called blankdisk.img (instead of test1.img):

        guestfish -N blankdisk.img=disk:200M

   -N disk - create a blank disk
       "guestfish -N [filename=]disk[:size]"

       Create a blank disk, size 1G (by default).

       The default size can be changed by supplying an optional parameter.

       オプションのパラメーターは次のとおりです:

        Name          Default value
        size          1G            the size of the disk image

   -N part - create a partitioned disk
       "guestfish -N [filename=]part[:size[:partition]]"

       Create a disk with a single partition.  By default the size of the disk is 1G (the
       available space in the partition will be a tiny bit smaller)  and the partition table will
       be MBR (old DOS-style).

       These defaults can be changed by supplying optional parameters.

       オプションのパラメーターは次のとおりです:

        Name          Default value
        size          1G            the size of the disk image
        partition     mbr           partition table type

   -N fs - create a filesystem
       "guestfish -N [filename=]fs[:filesystem[:size[:partition]]]"

       Create a disk with a single partition, with the partition containing an empty filesystem.
       This defaults to creating a 1G disk (the available space in the filesystem will be a tiny
       bit smaller) with an MBR (old DOS-style) partition table and an ext2 filesystem.

       These defaults can be changed by supplying optional parameters.

       オプションのパラメーターは次のとおりです:

        Name          Default value
        filesystem    ext2          the type of filesystem to use
        size          1G            the size of the disk image
        partition     mbr           partition table type

   -N lv - create a disk with logical volume
       "guestfish -N [filename=]lv[:name[:size[:partition]]]"

       Create a disk with a single partition, set up the partition as an LVM2 physical volume,
       and place a volume group and logical volume on there.  This defaults to creating a 1G disk
       with the VG and LV called "/dev/VG/LV".  You can change the name of the VG and LV by
       supplying an alternate name as the first optional parameter.

       Note this does not create a filesystem.  Use 'lvfs' to do that.

       オプションのパラメーターは次のとおりです:

        Name          Default value
        name          /dev/VG/LV    the name of the VG and LV to use
        size          1G            the size of the disk image
        partition     mbr           partition table type

   -N lvfs - create a disk with logical volume and filesystem
       "guestfish -N [filename=]lvfs[:name[:filesystem[:size[:partition]]]]"

       Create a disk with a single partition, set up the partition as an LVM2 physical volume,
       and place a volume group and logical volume on there.  Then format the LV with a
       filesystem.  This defaults to creating a 1G disk with the VG and LV called "/dev/VG/LV",
       with an ext2 filesystem.

       オプションのパラメーターは次のとおりです:

        Name          Default value
        name          /dev/VG/LV    the name of the VG and LV to use
        filesystem    ext2          the type of filesystem to use
        size          1G            the size of the disk image
        partition     mbr           partition table type

   -N bootroot - create a boot and root filesystem
       "guestfish -N [filename=]bootroot[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]"

       Create a disk with two partitions, for boot and root filesystem.  Format the two
       filesystems independently.  There are several optional parameters which control the exact
       layout and filesystem types.

       オプションのパラメーターは次のとおりです:

        Name          Default value
        bootfs        ext2          the type of filesystem to use for boot
        rootfs        ext2          the type of filesystem to use for root
        size          1G            the size of the disk image
        bootsize      128M          the size of the boot filesystem
        partition     mbr           partition table type

   -N bootrootlv - create a boot and root filesystem using LVM
       "guestfish -N
       [filename=]bootrootlv[:name[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]]"

       This is the same as "bootroot" but the root filesystem (only) is placed on a logical
       volume, named by default "/dev/VG/LV".  There are several optional parameters which
       control the exact layout.

       オプションのパラメーターは次のとおりです:

        Name          Default value
        name          /dev/VG/LV    the name of the VG and LV for root
        bootfs        ext2          the type of filesystem to use for boot
        rootfs        ext2          the type of filesystem to use for root
        size          1G            the size of the disk image
        bootsize      128M          the size of the boot filesystem
        partition     mbr           partition table type

ADDING REMOTE STORAGE

       For API-level documentation on this topic, see "guestfs_add_drive_opts" in guestfs(3) and
       "REMOTE STORAGE" in guestfs(3).

       On the command line, you can use the -a option to add network block devices using a URI-
       style format, for example:

        guestfish -a ssh://root@example.com/disk.img

       URIs cannot be used with the "add" command.  The equivalent command using the API directly
       is:

        ><fs> add /disk.img protocol:ssh server:tcp:example.com username:root

       The possible -a URI formats are described below.

   -a disk.img
   -a file:///path/to/disk.img
       Add the local disk image (or device) called disk.img.

   -a ftp://[user@]example.com[:port]/disk.img
   -a ftps://[user@]example.com[:port]/disk.img
   -a http://[user@]example.com[:port]/disk.img
   -a https://[user@]example.com[:port]/disk.img
   -a tftp://[user@]example.com[:port]/disk.img
       Add a disk located on a remote FTP, HTTP or TFTP server.

       The equivalent API command would be:

        ><fs> add /disk.img protocol:(ftp|...) server:tcp:example.com

   -a gluster://example.com[:port]/volname/image
       Add a disk image located on GlusterFS storage.

       The server is the one running "glusterd", and may be "localhost".

       The equivalent API command would be:

        ><fs> add volname/image protocol:gluster server:tcp:example.com

   -a iscsi://example.com[:port]/target-iqn-name[/lun]
       Add a disk located on an iSCSI server.

       The equivalent API command would be:

        ><fs> add target-iqn-name/lun protocol:iscsi server:tcp:example.com

   -a nbd://example.com[:port]
   -a nbd://example.com[:port]/exportname
   -a nbd://?socket=/socket
   -a nbd:///exportname?socket=/socket
       Add a disk located on Network Block Device (nbd) storage.

       The exportname part of the URI specifies an NBD export name, but is usually left empty.

       The optional ?socket parameter can be used to specify a Unix domain socket that we talk to
       the NBD server over.  Note that you cannot mix server name (ie. TCP/IP) and socket path.

       The equivalent API command would be (no export name):

        ><fs> add "" protocol:nbd server:[tcp:example.com|unix:/socket]

   -a rbd:///pool/disk
   -a rbd://example.com[:port]/pool/disk
       Add a disk image located on a Ceph (RBD/librbd) storage volume.

       Although libguestfs and Ceph supports multiple servers, only a single server can be
       specified when using this URI syntax.

       The equivalent API command would be:

        ><fs> add pool/disk protocol:rbd server:tcp:example.com:port

   -a sheepdog://[example.com[:port]]/volume/image
       Add a disk image located on a Sheepdog volume.

       The server name is optional.  Although libguestfs and Sheepdog supports multiple servers,
       only at most one server can be specified when using this URI syntax.

       The equivalent API command would be:

        ><fs> add volume protocol:sheepdog [server:tcp:example.com]

   -a ssh://[user@]example.com[:port]/disk.img
       Add a disk image located on a remote server, accessed using the Secure Shell (ssh) SFTP
       protocol.  SFTP is supported out of the box by all major SSH servers.

       The equivalent API command would be:

        ><fs> add /disk protocol:ssh server:tcp:example.com [username:user]

       Note that the URIs follow the syntax of RFC 3986: in particular, there are restrictions on
       the allowed characters for the various components of the URI.  Characters such as ":",
       "@", and "/" must be percent-encoded:

        $ guestfish -a ssh://user:pass%40word@example.com/disk.img

       In this case, the password is "pass@word".

進行状況バー

       Some (not all) long-running commands send progress notification messages as they are
       running.  Guestfish turns these messages into progress bars.

       When a command that supports progress bars takes longer than two seconds to run, and if
       progress bars are enabled, then you will see one appearing below the command:

        ><fs> copy-size /large-file /another-file 2048M
        / 10% [#####-----------------------------------------] 00:30

       The spinner on the left hand side moves round once for every progress notification
       received from the backend.  This is a (reasonably) golden assurance that the command is
       "doing something" even if the progress bar is not moving, because the command is able to
       send the progress notifications.  When the bar reaches 100% and the command finishes, the
       spinner disappears.

       Progress bars are enabled by default when guestfish is used interactively.  You can enable
       them even for non-interactive modes using --progress-bars, and you can disable them
       completely using --no-progress-bars.

PROMPT

       You can change or add colours to the default prompt ("><fs>") by setting the
       "GUESTFISH_PS1" environment variable.  A second string ("GUESTFISH_OUTPUT") is printed
       after the command has been entered and before the output, allowing you to control the
       colour of the output.  A third string ("GUESTFISH_INIT")  is printed before the welcome
       message, allowing you to control the colour of that message.  A fourth string
       ("GUESTFISH_RESTORE") is printed before guestfish exits.

       A simple prompt can be set by setting "GUESTFISH_PS1" to an alternate string:

        $ GUESTFISH_PS1='(type a command) '
        $ export GUESTFISH_PS1
        $ guestfish
        [...]
        (type a command) ▂

       You can also use special escape sequences, as described in the table below:

       \\  文字としてのバックスラッシュ文字。

       \[
       \]  (These should only be used in "GUESTFISH_PS1".)

           Place non-printing characters (eg. terminal control codes for colours) between
           "\[...\]".  What this does it to tell the readline(3) library that it should treat
           this subsequence as zero-width, so that command-line redisplay, editing etc works.

       \a  ベル文字。

       \e  ASCII ESC (エスケープ) 文字。

       \n  改行。

       \r  復帰。

       \NNN
           コードの8 進値が NNN の ASCII 文字。

       \xNN
           コードの 16 進値が NN の ASCII 文字。

   EXAMPLES OF PROMPTS
       Note that these examples require a terminal that supports ANSI escape codes.

       •

            GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '

           A bold black version of the ordinary prompt.

       •

            GUESTFISH_PS1='\[\e[1;32m\]><fs>\[\e[0;31m\] '
            GUESTFISH_OUTPUT='\e[0m'
            GUESTFISH_RESTORE="$GUESTFISH_OUTPUT"
            GUESTFISH_INIT='\e[1;34m'

           Blue welcome text, green prompt, red commands, black command output.

WINDOWS 8

       Windows 8 "fast startup" can prevent guestfish from mounting NTFS partitions.  See
       "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in guestfs(3).

guestfish コマンド

The commands in this section are guestfish convenience commands, in other words, they are
not part of the guestfs(3) API.

help
help
help cmd
help -l|--list

Without any parameter, this provides general help.

With a "cmd" parameter, this displays detailed help for that command.

With -l or --list, this list all commands.

exit
quit
これは guestfish を終了します。"^D" キーを使用することもできます。

alloc
allocate
alloc filename size

This creates an empty (zeroed) file of the given size, and then adds so it can be further
examined.

For more advanced image creation, see "disk-create".

Size can be specified using standard suffixes, eg. "1M".

スパースなファイルを作成するには、代わりに "sparse" を使用します。非スパースなディスクイ
メージを作成するには、 "準備済みディスクイメージ" を参照してください。

copy-in
copy-in local [local ...] /remotedir

"copy-in" copies local files or directories recursively into the disk image, placing them
in the directory called /remotedir (which must exist). This guestfish meta-command turns
into a sequence of "tar-in" and other commands as necessary.

Multiple local files and directories can be specified, but the last parameter must always
be a remote directory. Wildcards cannot be used.

copy-out
copy-out remote [remote ...] localdir

"copy-out" copies remote files or directories recursively out of the disk image, placing
them on the host disk in a local directory called "localdir" (which must exist). This
guestfish meta-command turns into a sequence of "download", "tar-out" and other commands
as necessary.

Multiple remote files and directories can be specified, but the last parameter must always
be a local directory. To download to the current directory, use "." as in:

copy-out /home .

Wildcards cannot be used in the ordinary command, but you can use them with the help of
"glob" like this:

glob copy-out /home/* .

delete-event
delete-event name

Delete the event handler which was previously registered as "name". If multiple event
handlers were registered with the same name, they are all deleted.

guestfish コマンドの "event" および "list-events" 参照。

display
display filename

Use "display" (a graphical display program) to display an image file. It downloads the
file, and runs "display" on it.

To use an alternative program, set the "GUESTFISH_DISPLAY_IMAGE" environment variable.
For example to use the GNOME display program:

export GUESTFISH_DISPLAY_IMAGE=eog

display(1) 参照。

echo
echo [params ...]

パラメーターを端末に返します。

edit
vi
emacs
edit filename

This is used to edit a file. It downloads the file, edits it locally using your editor,
then uploads the result.

The editor is $EDITOR. However if you use the alternate commands "vi" or "emacs" you will
get those corresponding editors.

event
event name eventset "shell script ..."

Register a shell script fragment which is executed when an event is raised. See
"guestfs_set_event_callback" in guestfs(3) for a discussion of the event API in
libguestfs.

The "name" parameter is a name that you give to this event handler. It can be any string
(even the empty string) and is simply there so you can delete the handler using the
guestfish "delete-event" command.

The "eventset" parameter is a comma-separated list of one or more events, for example
"close" or "close,trace". The special value "*" means all events.

The third and final parameter is the shell script fragment (or any external command) that
is executed when any of the events in the eventset occurs. It is executed using "$SHELL
-c", or if $SHELL is not set then /bin/sh -c.

The shell script fragment receives callback parameters as arguments $1, $2 etc. The
actual event that was called is available in the environment variable $EVENT.

event "" close "echo closed"
event messages appliance,library,trace "echo $@"
event "" progress "echo progress: $3/$4"
event "" * "echo $EVENT $@"

guestfish コマンドの "delete-event" および "list-events" 参照。

glob
glob command args...

Expand wildcards in any paths in the args list, and run "command" repeatedly on each
matching path.

"WILDCARDS AND GLOBBING" 参照。

hexedit
hexedit <filename|device>
hexedit <filename|device> <max>
hexedit <filename|device> <start> <max>

Use hexedit (a hex editor) to edit all or part of a binary file or block device.

This command works by downloading potentially the whole file or device, editing it
locally, then uploading it. If the file or device is large, you have to specify which
part you wish to edit by using "max" and/or "start" "max" parameters. "start" and "max"
are specified in bytes, with the usual modifiers allowed such as "1M" (1 megabyte).

For example to edit the first few sectors of a disk you might do:

hexedit /dev/sda 1M

which would allow you to edit anywhere within the first megabyte of the disk.

To edit the superblock of an ext2 filesystem on /dev/sda1, do:

hexedit /dev/sda1 0x400 0x400

(assuming the superblock is in the standard location).

This command requires the external hexedit(1) program. You can specify another program to
use by setting the "HEXEDITOR" environment variable.

"hexdump" 参照。

lcd
lcd directory

Change the local directory, ie. the current directory of guestfish itself.

Note that "!cd" won't do what you might expect.

list-events
list-events

List the event handlers registered using the guestfish "event" command.

man
manual
man

guestfish のマニュアルページを開きます。

more
less
more filename

less filename

ファイルを表示するために使用します。

デフォルトのビューアーは $PAGER です。 しかし代替のコマンド "less" を使用すると、明示的に
"less" コマンドが使えます。

reopen
reopen

Close and reopen the libguestfs handle. It is not necessary to use this normally, because
the handle is closed properly when guestfish exits. However this is occasionally useful
for testing.

setenv
setenv VAR value

環境変数 "VAR" を文字列 "value" に設定します。

環境変数の値を表示するには、次のようにシェルコマンドを使用します:

!echo $VAR

sparse
sparse filename size

This creates an empty sparse file of the given size, and then adds so it can be further
examined.

In all respects it works the same as the "alloc" command, except that the image file is
allocated sparsely, which means that disk blocks are not assigned to the file until they
are needed. Sparse disk files only use space when written to, but they are slower and
there is a danger you could run out of real disk space during a write operation.

For more advanced image creation, see "disk-create".

Size can be specified using standard suffixes, eg. "1M".

See also the guestfish "scratch" command.

supported
supported

This command returns a list of the optional groups known to the daemon, and indicates
which ones are supported by this build of the libguestfs appliance.

"AVAILABILITY" in guestfs(3) 参照。

time
time command args...

Run the command as usual, but print the elapsed time afterwards. This can be useful for
benchmarking operations.

unsetenv
unsetenv VAR

環境から "VAR" を削除します。

コマンド

acl-delete-def-file
acl-delete-def-file dir

この関数はディレクトリー "dir" に設定されている標準の POSIX アクセス制御リスト (ACL:
Access Control List) を削除します。

This command depends on the feature "acl". See also "feature-available".

acl-get-file
acl-get-file path acltype

This function returns the POSIX Access Control List (ACL) attached to "path". The ACL is
returned in "long text form" (see acl(5)).

The "acltype" parameter may be:

"access"
Return the ordinary (access) ACL for any file, directory or other filesystem object.

"default"
Return the default ACL. Normally this only makes sense if "path" is a directory.

This command depends on the feature "acl". See also "feature-available".

acl-set-file
acl-set-file path acltype acl

This function sets the POSIX Access Control List (ACL) attached to "path".

The "acltype" parameter may be:

"access"
Set the ordinary (access) ACL for any file, directory or other filesystem object.

"default"
Set the default ACL. Normally this only makes sense if "path" is a directory.

The "acl" parameter is the new ACL in either "long text form" or "short text form" (see
acl(5)). The new ACL completely replaces any previous ACL on the file. The ACL must
contain the full Unix permissions (eg. "u::rwx,g::rx,o::rx").

If you are specifying individual users or groups, then the mask field is also required
(eg. "m::rwx"), followed by the "u:ID:..." and/or "g:ID:..." field(s). A full ACL string
might therefore look like this:

u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
\ Unix permissions / \mask/ \ ACL /

You should use numeric UIDs and GIDs. To map usernames and groupnames to the correct
numeric ID in the context of the guest, use the Augeas functions (see "aug-init").

This command depends on the feature "acl". See also "feature-available".

add-cdrom
add-cdrom filename

この関数は仮想 CD-ROM ディスクイメージを仮想マシンに追加します。

The image is added as read-only drive, so this function is equivalent of "add-drive-ro".

This function is deprecated. In new code, use the "add-drive-ro" call instead.

Deprecated functions will not be removed from the API, but the fact that they are
deprecated indicates that there are problems with correct use of these functions.

add-domain
domain
add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..] [cachemode:..] [discard:..] [copyonread:true|false]

This function adds the disk(s) attached to the named libvirt domain "dom". It works by
connecting to libvirt, requesting the domain and domain XML from libvirt, parsing it for
disks, and calling "add-drive-opts" on each one.

The number of disks added is returned. This operation is atomic: if an error is returned,
then no disks are added.

This function does some minimal checks to make sure the libvirt domain is not running
(unless "readonly" is true). In a future version we will try to acquire the libvirt lock
on each disk.

Disks must be accessible locally. This often means that adding disks from a remote
libvirt connection (see https://libvirt.org/remote.html) will fail unless those disks are
accessible via the same device path locally too.

The optional "libvirturi" parameter sets the libvirt URI (see
https://libvirt.org/uri.html). If this is not set then we connect to the default libvirt
URI (or one set through an environment variable, see the libvirt documentation for full
details).

The optional "live" flag controls whether this call will try to connect to a running
virtual machine "guestfsd" process if it sees a suitable <channel> element in the libvirt
XML definition. The default (if the flag is omitted) is never to try. See "ATTACHING TO
RUNNING DAEMONS" in guestfs(3) for more information.

If the "allowuuid" flag is true (default is false) then a UUID may be passed instead of
the domain name. The "dom" string is treated as a UUID first and looked up, and if that
lookup fails then we treat "dom" as a name as usual.

The optional "readonlydisk" parameter controls what we do for disks which are marked
<readonly/> in the libvirt XML. Possible values are:

readonlydisk = "error"
"readonly" が偽ならば:

The whole call is aborted with an error if any disk with the <readonly/> flag is
found.

"readonly" が真ならば:

<readonly/> フラグを持つディスクは読み込み専用で追加されます。

readonlydisk = "read"
"readonly" が偽ならば:

<readonly/> フラグを持つディスクは読み込み専用で追加されます。他のディスクは読み書き用
で追加されます。

"readonly" が真ならば:

<readonly/> フラグを持つディスクは読み込み専用で追加されます。

readonlydisk = "write" (デフォルト)
"readonly" が偽ならば:

<readonly/> フラグを持つディスクは読み書き用で追加されます。

"readonly" が真ならば:

<readonly/> フラグを持つディスクは読み込み専用で追加されます。

readonlydisk = "ignore"
"readonly" が真または偽ならば:

<readonly/> フラグのあるディスクはスキップされます

If present, the value of "logical_block_size" attribute of <blockio/> tag in libvirt XML
will be passed as "blocksize" parameter to "add-drive-opts".

他のオプション引数は直接 "add-drive-opts" に渡されます。

このコマンドは 1 つまたはそれ以上のオプション引数を持つ必要があります。 "オプション引数"
を参照してください。

add-drive
add
add-drive-opts
add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false] [blocksize:N]

This function adds a disk image called filename to the handle. filename may be a regular
host file or a host device.

When this function is called before "launch" (the usual case) then the first time you call
this function, the disk appears in the API as /dev/sda, the second time as /dev/sdb, and
so on.

In libguestfs ≥ 1.20 you can also call this function after launch (with some
restrictions). This is called "hotplugging". When hotplugging, you must specify a
"label" so that the new disk gets a predictable name. For more information see
"HOTPLUGGING" in guestfs(3).

You don't necessarily need to be root when using libguestfs. However you obviously do
need sufficient permissions to access the filename for whatever operations you want to
perform (ie. read access if you just want to read the image or write access if you want to
modify the image).

This call checks that filename exists.

filename may be the special string "/dev/null". See "NULL DISKS" in guestfs(3).

オプション引数は次のとおりです:

"readonly"
If true then the image is treated as read-only. Writes are still allowed, but they
are stored in a temporary snapshot overlay which is discarded at the end. The disk
that you add is not modified.

"format"
This forces the image format. If you omit this (or use "add-drive" or "add-drive-ro")
then the format is automatically detected. Possible formats include "raw" and
"qcow2".

Automatic detection of the format opens you up to a potential security hole when
dealing with untrusted raw-format images. See CVE-2010-3851 and RHBZ#642934.
Specifying the format closes this security hole.

"iface"
This rarely-used option lets you emulate the behaviour of the deprecated "add-drive-
with-if" call (q.v.)

"name"
The name the drive had in the original guest, e.g. /dev/sdb. This is used as a hint
to the guest inspection process if it is available.

"label"
Give the disk a label. The label should be a unique, short string using only ASCII
characters "[a-zA-Z]". As well as its usual name in the API (such as /dev/sda), the
drive will also be named /dev/disk/guestfs/label.

"ディスクラベル" in guestfs(3)を参照してください。

"protocol"
The optional protocol argument can be used to select an alternate source protocol.

See also: "REMOTE STORAGE" in guestfs(3).

"protocol = "file""
filename is interpreted as a local file or device. This is the default if the
optional protocol parameter is omitted.

"protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
Connect to a remote FTP, HTTP or TFTP server. The "server" parameter must also be
supplied - see below.

See also: "FTP, HTTP AND TFTP" in guestfs(3)

"protocol = "gluster""
Connect to the GlusterFS server. The "server" parameter must also be supplied -
see below.

終了ステータス

       コマンドがエラーなく完了すると、guestfish は 0 を返します。エラーがあると 1 を返します。

環境変数

EDITOR
"edit" コマンドはエディターとして $EDITOR を使用します。設定されていないと、"vi" を使
用します。

GUESTFISH_DISPLAY_IMAGE
The "display" command uses $GUESTFISH_DISPLAY_IMAGE to display images. If not set, it
uses display(1).

GUESTFISH_INIT
Printed when guestfish starts. See "PROMPT".

GUESTFISH_OUTPUT
Printed before guestfish output. See "PROMPT".

GUESTFISH_PID
Used with the --remote option to specify the remote guestfish process to control. See
section "REMOTE CONTROL GUESTFISH OVER A SOCKET".

GUESTFISH_PS1
Set the command prompt. See "PROMPT".

GUESTFISH_RESTORE
Printed before guestfish exits. See "PROMPT".

HEXEDITOR
The "hexedit" command uses $HEXEDITOR as the external hex editor. If not specified,
the external hexedit(1) program is used.

HOME
GNU readline のサポート付きでコンパイルしていると、ホームディレクトリーにあるさまざま
なファイルを使用できます。 "ファイル" 参照。

LIBGUESTFS_APPEND
仮想マシンのカーネルに追加のオプションを渡します。

LIBGUESTFS_ATTACH_METHOD
This is the old way to set "LIBGUESTFS_BACKEND".

LIBGUESTFS_BACKEND
Choose the default way to create the appliance. See "guestfs_set_backend" in
guestfs(3).

LIBGUESTFS_BACKEND_SETTINGS
A colon-separated list of backend-specific settings. See "BACKEND" in guestfs(3),
"BACKEND SETTINGS" in guestfs(3).

LIBGUESTFS_CACHEDIR
The location where libguestfs will cache its appliance, when using a supermin
appliance. The appliance is cached and shared between all handles which have the same
effective user ID.

If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If "TMPDIR" is not set,
then /var/tmp is used.

See also "LIBGUESTFS_TMPDIR", "set-cachedir".

LIBGUESTFS_DEBUG
Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the same effect as
using the -v option.

LIBGUESTFS_HV
Set the default hypervisor (usually qemu) binary that libguestfs uses. If not set,
then the qemu which was found at compile time by the configure script is used.

LIBGUESTFS_MEMSIZE
Set the memory allocated to the qemu process, in megabytes. For example:

LIBGUESTFS_MEMSIZE=700

LIBGUESTFS_PATH
Set the path that guestfish uses to search for kernel and initrd.img. See the
discussion of paths in guestfs(3).

LIBGUESTFS_QEMU
This is the old way to set "LIBGUESTFS_HV".

LIBGUESTFS_TMPDIR
The location where libguestfs will store temporary files used by each handle.

If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If "TMPDIR" is not set,
then /tmp is used.

See also "LIBGUESTFS_CACHEDIR", "set-tmpdir".

LIBGUESTFS_TRACE
コマンドトレースを有効にするには "LIBGUESTFS_TRACE=1" を設定してください。

PAGER
The "more" command uses $PAGER as the pager. If not set, it uses "more".

パス
Libguestfs and guestfish may run some external programs, and rely on $PATH being set
to a reasonable value. If using the libvirt backend, libvirt will not work at all
unless $PATH contains the path of qemu/KVM.

SUPERMIN_KERNEL
SUPERMIN_KERNEL_VERSION
SUPERMIN_MODULES
These three environment variables allow the kernel that libguestfs uses in the
appliance to be selected. If $SUPERMIN_KERNEL is not set, then the most recent host
kernel is chosen. For more information about kernel selection, see supermin(1).

TMPDIR
See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".

XDG_RUNTIME_DIR
This directory represents a user-specific directory for storing non-essential runtime
files.

If it is set, then is used to store temporary sockets. Otherwise, /tmp is used.

See also "get-sockdir", http://www.freedesktop.org/wiki/Specifications/basedir-spec/.

ファイル

       $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
       $HOME/.libguestfs-tools.rc
       $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
       /etc/libguestfs-tools.conf
           This configuration file controls the default read-only or read-write mode (--ro or
           --rw).

           See libguestfs-tools.conf(5).

       $HOME/.guestfish
           GNU readline のサポート付きでコンパイルされていると、コマンドの履歴がこのファイルに保
           存されます。

       $HOME/.inputrc
       /etc/inputrc
           GNU readline のサポート付きでコンパイルされていると、これらのファイルが readline を設
           定するために使用されます。  詳細は "INITIALIZATION FILE" in readline(3) を参照してくだ
           さい。

           To write rules which only apply to guestfish, use:

            $if guestfish
            ...
            $endif

           Variables that you can set in inputrc that change the behaviour of guestfish in useful
           ways include:

           completion-ignore-case (初期値: on)
               By default, guestfish will ignore case when tab-completing paths on the disk.
               Use:

                set completion-ignore-case off

               guestfish が大文字小文字を区別するようになります。

       test1.img
       test2.img (etc)
           When using the -N or --new option, the prepared disk or filesystem will be created in
           the file test1.img in the current directory.  The second use of -N will use test2.img
           and so on.  Any existing file with the same name will be overwritten.  You can use a
           different filename by using the "filename=" prefix.

著者

       Richard W.M. Jones ("rjones at redhat dot com")

COPYRIGHT

       Copyright (C) 2009-2020 Red Hat Inc.

LICENSE

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
       Boston, MA 02110-1301 USA.

BUGS

       To get a list of bugs against libguestfs, use this link:
       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

       To report a new bug against libguestfs, use this link:
       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

       When reporting a bug, please supply:

       •   The version of libguestfs.

       •   Where you got libguestfs (eg. which Linux distro, compiled from source, etc)

       •   Describe the bug accurately and give a way to reproduce it.

       •   Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug
           report.

名前

書式

説明

例

オプション

コマンドラインにおけるコマンド

launch (または run) の使用法

OPENING DISKS FOR READ AND WRITE

QUOTING

オプション引数

数値

ワイルドカードおよびグロブ

コメント

ローカルのコマンドの実行法

パイプ

ホームディレクトリ

暗号化ディスク

Windows のパス

ファイルのアップロード方法およびダウンロード方法

EXIT ON ERROR BEHAVIOUR

guestfish のソケット経由のリモート制御

PREPARED DISK IMAGES

ADDING REMOTE STORAGE

進行状況バー

PROMPT

WINDOWS 8

guestfish コマンド

コマンド

終了ステータス

環境変数

ファイル

関連項目

著者

COPYRIGHT

LICENSE

BUGS