libvirt/docs/manpages/virt-login-shell.rst
Daniel P. Berrangé a7464a3f01 docs: use "::" instead of ".. code-block::"
The former is a short hand for the latter and is already widely used in
the docs. Using the short hand avoids incompatibility with the alternate
impl of rst2html5.

Reviewed-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-10-05 13:05:47 +01:00

145 lines
3.2 KiB
ReStructuredText

================
virt-login-shell
================
------------------------------------------
tool to execute a shell within a container
------------------------------------------
:Manual section: 1
:Manual group: Virtualization Support
.. contents::
SYNOPSIS
========
``virt-login-shell`` [*OPTION*]
DESCRIPTION
===========
The ``virt-login-shell`` program is a setuid shell that is used to join
an LXC container that matches the user's name. If the container is not
running, ``virt-login-shell`` will attempt to start the container.
``virt-login-shell`` is not allowed to be run by root. Normal users will get
added to a container that matches their username, if it exists, and they are
configured in ``/etc/libvirt/virt-login-shell.conf``.
The basic structure of most ``virt-login-shell`` usage is:
::
virt-login-shell
OPTIONS
=======
``-c CMD``
Instruct the shell to run CMD instead of presenting an
interactive shell prompt.
``-h``, ``--help``
Display command line help usage then exit.
``-V``, ``--version``
Display version information then exit.
CONFIG
======
By default, ``virt-login-shell`` will execute the ``/bin/sh`` program for
the user. You can modify this behaviour by defining the shell variable in
``/etc/libvirt/virt-login-shell.conf``. e.g.
::
shell = [ "/bin/bash" ]
If the ``auto_shell`` config option is set then it will attempt to automatically
detect the shell from ``/etc/password`` inside the container. This should only
be done if the container has a separate ``/etc`` directory from the host,
otherwise it will end up recursively invoking ``virt-login-shell``. e.g.
::
auto_shell = 1
By default no users are allowed to use virt-login-shell, if you want to allow
certain users to use virt-login-shell, you need to modify the allowed_users
variable in /etc/libvirt/virt-login-shell.conf. e.g.
::
allowed_users = [ "tom", "dick", "harry" ]
EXIT STATUS
===========
``virt-login-shell`` normally returns the exit status of the command it
executed. If the command was killed by a signal, but that signal is not
fatal to virt-login-shell, then it returns the signal number plus 128.
Exit status generated by ``virt-login-shell`` itself:
* ``0`` An option was used to learn more about this binary.
* ``125`` Generic error before attempting execution of the configured shell; for example, if libvirtd is not running.
* ``126`` The configured shell exists but could not be executed.
* ``127`` The configured shell could not be found.
BUGS
====
Please report all bugs you discover. This should be done via either:
#. the mailing list
`https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_
#. the bug tracker
`https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_
Alternatively, you may report bugs to your software distributor / vendor.
AUTHOR
======
Daniel Walsh
COPYRIGHT
=========
Copyright (C) 2013-2014 Red Hat, Inc., and the authors listed in the
libvirt AUTHORS file.
LICENSE
=======
``virt-login-shell`` is distributed under the terms of the GNU LGPL v2+.
This is free software; see the source for copying conditions. There
is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE
SEE ALSO
========
virsh(1), `https://libvirt.org/ <https://libvirt.org/>`_