=head1 NAME

guestfsd - guestfs daemon

=head1 SYNOPSIS

 guestfsd [-r] [-v|--verbose]

=head1 DESCRIPTION

C<guestfsd> is the libguestfs daemon.  Normal users never need to run
this program explicitly.  This man page discusses what C<guestfsd>
does in both the libguestfs appliance and when using libguestfs live.

=head2 LIBGUESTFS APPLIANCE

For the architecture of the libguestfs appliance, see
L<guestfs(3)/ARCHITECTURE>.

After the appliance boots, the F</init> script in the appliance starts
C<guestfsd> with no arguments.  C<guestfsd> opens the virtio-serial
port on a known path (see L</FILES>).  It initiates the protocol (see
L<guestfs(3)/COMMUNICATION PROTOCOL>) and processes requests one at a
time from the library until the appliance is destroyed.

Filesystems are mounted under F</sysroot> and all filesystem
operations happen relative to this directory.

=head2 LIBGUESTFS LIVE

In the libguestfs live case, C<guestfsd -r> is started from the
rc-scripts, systemd, etc.

The C<-r> option causes the daemon to operate on the root filesystem
instead of F</sysroot>.

Currently (because of limitations in virtio-serial) only one client
can connect at a time, and C<guestfsd> must be restarted after each
client disconnects.  If libguestfs live were changed to use a
different transport such as TCP/IP then this limitation could be
removed.

=head1 OPTIONS

=over 4

=item B<-?>

=item B<--help>

Display brief help.

=item B<-c> CHANNEL

=item B<--channel> CHANNEL

=item B<--channel> fd:N

Pass the name of the virtio-serial channel, serial port, etc.  over
which guestfsd will communicate with the library.  If this parameter
is not given, then an internal default port is used.

The C<fd:N> form causes guestfsd to use the file descriptor C<N>
directly.

=item B<-l>

=item B<--listen>

Instead of opening the C<guestfs_channel> and thus expecting that it
already exists, create the channel as a Unix domain socket, listen on
it, and accept a single connection.  This is mainly used for testing
the daemon.

=item B<-n>

=item B<--network>

Enable network features in the daemon.

=item B<-r>

Set the root filesystem to be F</> (instead of the default which is
F</sysroot>).  Also do not unmount filesystems when the daemon exits.

This option is used to enable libguestfs live.

=item B<-v>

=item B<--verbose>

Enable verbose messages for debugging.

The verbose flag is also set if the Linux command line contains the
substring C<guestfs_verbose=1>.

=back

=head1 EXIT STATUS

This program returns 0 if successful, or non-zero if there was an
error.

=head1 FILES

=over 4

=item F</dev/virtio-ports/org.libguestfs.channel.0>

The virtio serial port which C<guestfsd> connects to.

=item F</proc/cmdline>

The Linux command line is parsed to discover C<guestfs_*> flags.  The
following flags are understood:

=over 4

=item B<guestfs_verbose=1>

Enable verbose messages.  This flag is passed by the libguestfs
library to the appliance to make the daemon more verbose (it acts like
the I<-v> flag on the command line).  Unrelated to the daemon, it also
causes the appliance init script to print out a lot more debugging
information.

=item B<guestfs_channel=PATH>

Set the path to the virtio-serial channel to something other than the
default (which is F</dev/virtio-ports/org.libguestfs.channel.0>).
This is used by the User-Mode Linux backend to use a regular emulated
serial port instead of virtio-serial.

=item B<guestfs_network=1>

This is set if the appliance network is enabled (see
C<guestfs_set_network>).

=back

=back

=head1 SEE ALSO

L<guestfs(3)>,
L<http://libguestfs.org/>.

=head1 AUTHOR

Richard W.M. Jones L<http://people.redhat.com/~rjones/>

=head1 COPYRIGHT

Copyright (C) 2009-2025 Red Hat Inc.