================
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:

.. code-block::

   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.

.. code-block::

   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.

.. code-block::

   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.

.. code-block::

   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/>`_
