.\" Man page generated from reStructuredText.
.
.TH VIRT-LOGIN-SHELL 1 "" "" "Virtualization Support"
.SH NAME
virt-login-shell \- tool to execute a shell within a container
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%SYNOPSIS\fP
.IP \(bu 2
\fI\%DESCRIPTION\fP
.IP \(bu 2
\fI\%OPTIONS\fP
.IP \(bu 2
\fI\%CONFIG\fP
.IP \(bu 2
\fI\%EXIT STATUS\fP
.IP \(bu 2
\fI\%BUGS\fP
.IP \(bu 2
\fI\%AUTHOR\fP
.IP \(bu 2
\fI\%COPYRIGHT\fP
.IP \(bu 2
\fI\%LICENSE\fP
.IP \(bu 2
\fI\%SEE ALSO\fP
.UNINDENT
.SH SYNOPSIS
.sp
\fBvirt\-login\-shell\fP [\fIOPTION\fP]
.SH DESCRIPTION
.sp
The \fBvirt\-login\-shell\fP program is a setuid shell that is used to join
an LXC container that matches the user\(aqs name.  If the container is not
running, \fBvirt\-login\-shell\fP will attempt to start the container.
\fBvirt\-login\-shell\fP 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 \fB/etc/libvirt/virt\-login\-shell.conf\fP\&.
.sp
The basic structure of most \fBvirt\-login\-shell\fP usage is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virt\-login\-shell
.ft P
.fi
.UNINDENT
.UNINDENT
.SH OPTIONS
.sp
\fB\-c CMD\fP
.sp
Instruct the shell to run CMD instead of presenting an
interactive shell prompt.
.sp
\fB\-h\fP, \fB\-\-help\fP
.sp
Display command line help usage then exit.
.sp
\fB\-V\fP, \fB\-\-version\fP
.sp
Display version information then exit.
.SH CONFIG
.sp
By default, \fBvirt\-login\-shell\fP will execute the \fB/bin/sh\fP program for
the user. You can modify this behaviour by defining the shell variable in
\fB/etc/libvirt/virt\-login\-shell.conf\fP\&. e.g.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
shell = [ "/bin/bash" ]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the \fBauto_shell\fP config option is set then it will attempt to automatically
detect the shell from \fB/etc/password\fP inside the container. This should only
be done if the container has a separate \fB/etc\fP directory from the host,
otherwise it will end up recursively invoking \fBvirt\-login\-shell\fP\&. e.g.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
auto_shell = 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
allowed_users = [ "tom", "dick", "harry" ]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH EXIT STATUS
.sp
\fBvirt\-login\-shell\fP 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.
.sp
Exit status generated by \fBvirt\-login\-shell\fP itself:
.INDENT 0.0
.IP \(bu 2
\fB0\fP An option was used to learn more about this binary.
.IP \(bu 2
\fB125\fP Generic error before attempting execution of the configured shell; for example, if libvirtd is not running.
.IP \(bu 2
\fB126\fP The configured shell exists but could not be executed.
.IP \(bu 2
\fB127\fP The configured shell could not be found.
.UNINDENT
.SH BUGS
.sp
Please report all bugs you discover.  This should be done via either:
.INDENT 0.0
.IP 1. 3
the mailing list
.sp
\fI\%https://libvirt.org/contact.html\fP
.IP 2. 3
the bug tracker
.sp
\fI\%https://libvirt.org/bugs.html\fP
.UNINDENT
.sp
Alternatively, you may report bugs to your software distributor / vendor.
.SH AUTHOR
.sp
Daniel Walsh
.SH COPYRIGHT
.sp
Copyright (C) 2013\-2014 Red Hat, Inc., and the authors listed in the
libvirt AUTHORS file.
.SH LICENSE
.sp
\fBvirt\-login\-shell\fP 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
.SH SEE ALSO
.sp
virsh(1), \fI\%https://libvirt.org/\fP
.\" Generated by docutils manpage writer.
.