SIMPLE SOLUTIONS

# GUESTFISH(1) - Linux man page online | User commands

The guest filesystem shell.

Chapter
2018-01-25
guestfish(1) Virtualization Support guestfish(1)

## NAME

guestfish - the guest filesystem shell

## SYNOPSIS

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

## WARNING

Using "guestfish" in write mode on live virtual machines, or concurrently with other disk editing tools, can be dangerous, potentially causing disk corruption. The virtual machine must be shut down before you use this command, and disk images must not be edited concurrently. Use the --ro (read-only) option to use "guestfish" safely if the disk image or virtual machine might be live. You may see strange or inconsistent results if running concurrently with other changes, but with this option you won't risk disk corruption.

## DESCRIPTION

Guestfish is a shell and command-line tool for examining and modifying virtual machine filesystems. It uses libguestfs and exposes all of the functionality of the guestfs API, see guestfs(3). Guestfish gives you structured access to the libguestfs API, from shell scripts or the command line or interactively. If you want to rescue a broken virtual machine image, you should look at the virt-rescue(1) command.

## COMMANDS ON COMMAND LINE

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. USING launch (OR 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 (aka run) · mount or -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" Alert (bell) character. "\b" Backspace character. "\f" Form feed character. "\n" Newline character. "\r" Carriage return character. "\t" Horizontal tab character. "\v" Vertical tab character. "\"" A literal double quote character. "\ooo" A character with octal value ooo. There must be precisely 3 octal digits (unlike C). "\xhh" A character with hex value hh. There must be precisely 2 hex digits. In the current implementation "\000" and "\x00" cannot be used in strings. "\\" A literal backslash character.

## OPTIONAL ARGUMENTS

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.

## NUMBERS

This section applies to all commands which can take integers as parameters. SIZE SUFFIX When the command takes a parameter measured in bytes, you can use one of the following suffixes to specify kilobytes, megabytes and larger sizes: k or K or KiB The size in kilobytes (multiplied by 1024). KB The size in SI 1000 byte units. M or MiB The size in megabytes (multiplied by 1048576). MB The size in SI 1000000 byte units. G or GiB The size in gigabytes (multiplied by 2**30). GB The size in SI 10**9 byte units. T or TiB The size in terabytes (multiplied by 2**40). TB The size in SI 10**12 byte units. P or PiB The size in petabytes (multiplied by 2**50). PB The size in SI 10**15 byte units. E or EiB The size in exabytes (multiplied by 2**60). EB The size in SI 10**18 byte units. Z or ZiB The size in zettabytes (multiplied by 2**70). ZB The size in SI 10**21 byte units. Y or YiB The size in yottabytes (multiplied by 2**80). YB The size in SI 10**24 byte units. For example: truncate-size /file 1G would truncate the file to 1 gigabyte. Be careful because a few commands take sizes in kilobytes or megabytes (eg. the parameter to "memsize" is specified in megabytes already). Adding a suffix will probably not do what you expect. OCTAL AND HEXADECIMAL NUMBERS 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 decimal number 1234 02322 octal number, equivalent to decimal 1234 0x4d2 hexadecimal number, equivalent to decimal 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 # OK chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal. 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).

## WILDCARDS AND GLOBBING

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. To perform wildcard expansion, use the "glob" command. 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.

## COMMENTS

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: # this is a comment # this is a comment foo # NOT a comment Blank lines are also ignored.

## RUNNING COMMANDS LOCALLY

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.

## PROGRESS BARS

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: \\ A literal backslash character.  (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 A bell character. \e An ASCII ESC (escape) character. \n A newline. \r A carriage return. \NNN The ASCII character whose code is the octal value NNN. \xNN The ASCII character whose code is the hex value NN. 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).

## EXIT STATUS

guestfish returns 0 if the commands completed without error, or 1 if there was an error.

## SEE ALSO

guestfs(3), http://libguestfs.org/, virt-alignment-scan(1), virt-builder(1), virt-cat(1), virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1), virt-diff(1), virt-edit(1), virt-filesystems(1), virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1), virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1), virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1), virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1), virt-win-reg(1), libguestfs-tools.conf(5), display(1), hexedit(1), supermin(1).

## AUTHORS

Richard W.M. Jones ("rjones at redhat dot com")
Copyright (C) 2009-2017 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.
libguestfs-1.36.13 2018-01-25 guestfish(1)
This manual Reference Other manuals
guestfish(1) referred by guestfs(3) | guestfs-building(1) | guestfs-faq(1) | guestfs-hacking(1) | guestfs-performance(1) | guestfs-recipes(1) | guestfs-release-notes(1) | guestfs-security(1) | guestfs-testing(1) | guestmount(1) | hivexsh(1) | libguestfs-tools.conf(5) | Sys::Guestfs(3pm) | virt-alignment-scan(1) | virt-builder(1) | virt-cat(1) | virt-copy-in(1) | virt-copy-out(1) | virt-customize(1) | virt-df(1)
refer to acl(5) | attr(5) | augtool(1) | blockdev(8) | btrfs(8) | cap_from_text(3) | chattr(1) | chmod(1) | cmp(1) | dump(8) | e2fsck(8) | extlinux(1) | file(1) | find(1) | fsck(8) | fsync(2) | getxattr(2) | glob(3) | gm(1) | guestfs(3)