Debian Codegraph @

doc/lxc-unshare.sgml.in

raw
1 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
2
3 <!DOCTYPE refentry PUBLIC @docdtd@ [
4
5 <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
6 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
7 ]>
8
9 <refentry>
10
11 <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
12
13 <refmeta>
14 <refentrytitle>lxc-unshare</refentrytitle>
15 <manvolnum>1</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>lxc-unshare</refname>
20
21 <refpurpose>
22 Run a task in a new set of namespaces.
23 </refpurpose>
24 </refnamediv>
25
26 <refsynopsisdiv>
27 <cmdsynopsis>
28 <command>lxc-unshare</command>
29 <arg choice="req">-s, --namespaces <replaceable>namespaces</replaceable></arg>
30 <arg choice="opt">-u, --user <replaceable>user</replaceable></arg>
31 <arg choice="opt">-H, --hostname <replaceable>hostname</replaceable></arg>
32 <arg choice="opt">-i, --ifname <replaceable>ifname</replaceable></arg>
33 <arg choice="opt">-d, --daemon</arg>
34 <arg choice="opt">-M, --remount</arg>
35 <arg choice="req">command</arg>
36 </cmdsynopsis>
37 </refsynopsisdiv>
38
39 <refsect1>
40 <title>Description</title>
41
42 <para>
43 <command>lxc-unshare</command> can be used to run a task in a cloned set
44 of namespaces. This command is mainly provided for testing purposes.
45 Despite its name, it always uses clone rather than unshare to create
46 the new task with fresh namespaces. Apart from testing kernel
47 regressions this should make no difference.
48 </para>
49
50 </refsect1>
51
52 <refsect1>
53
54 <title>Options</title>
55
56 <variablelist>
57
58 <varlistentry>
59 <term>
60 <option>-s, --namespaces <replaceable>namespaces</replaceable></option>
61 </term>
62 <listitem>
63 <para>
64 Specify the namespaces to attach to, as a pipe-separated list,
65 e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
66 <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
67 <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
68 <replaceable>USER </replaceable> and
69 <replaceable>NETWORK</replaceable>. This allows one to change
70 the context of the process to e.g. the network namespace of the
71 container while retaining the other namespaces as those of the
72 host. (The pipe symbol needs to be escaped, e.g.
73 <replaceable>MOUNT\|PID</replaceable> or quoted, e.g.
74 <replaceable>"MOUNT|PID"</replaceable>.)
75 </para>
76 </listitem>
77 </varlistentry>
78
79 <varlistentry>
80 <term>
81 <option>-u, --user <replaceable>user</replaceable></option>
82 </term>
83 <listitem>
84 <para>
85 Specify a userid which the new task should become.
86 </para>
87 </listitem>
88 </varlistentry>
89
90 <varlistentry>
91 <term>
92 <option>-H, --hostname <replaceable>hostname</replaceable></option>
93 </term>
94 <listitem>
95 <para>
96 Set the hostname in the new container. Only allowed if
97 the UTSNAME namespace is set.
98 </para>
99 </listitem>
100 </varlistentry>
101
102 <varlistentry>
103 <term>
104 <option>-i, --ifname <replaceable>interfacename</replaceable></option>
105 </term>
106 <listitem>
107 <para>
108 Move the named interface into the container. Only allowed
109 if the NETWORK namespace is set. You may specify this
110 argument multiple times to move multiple interfaces into
111 container.
112 </para>
113 </listitem>
114 </varlistentry>
115
116 <varlistentry>
117 <term>
118 <option>-d, --daemon</option>
119 </term>
120 <listitem>
121 <para>
122 Daemonize (do not wait for the container to exit before exiting)
123 </para>
124 </listitem>
125 </varlistentry>
126
127 <varlistentry>
128 <term>
129 <option>-M, --remount</option>
130 </term>
131 <listitem>
132 <para>
133 Mount default filesystems (/proc /dev/shm and /dev/mqueue)
134 in the container. Only allowed if MOUNT namespace is set.
135 </para>
136 </listitem>
137 </varlistentry>
138
139 </variablelist>
140
141 </refsect1>
142
143 <refsect1>
144 <title>Examples</title>
145 <para>
146 To spawn a new shell with its own UTS (hostname) namespace,
147 <programlisting>
148 lxc-unshare -s UTSNAME /bin/bash
149 </programlisting>
150 If the hostname is changed in that shell, the change will not be
151 reflected on the host.
152 </para>
153 <para>
154 To spawn a shell in a new network, pid, and mount namespace,
155 <programlisting>
156 lxc-unshare -s "NETWORK|PID|MOUNT" /bin/bash
157 </programlisting>
158 The resulting shell will have pid 1 and will see no network interfaces.
159 After re-mounting /proc in that shell,
160 <programlisting>
161 mount -t proc proc /proc
162 </programlisting>
163 ps output will show there are no other processes in the namespace.
164 </para>
165 <para>
166 To spawn a shell in a new network, pid, mount, and hostname
167 namespace.
168 <programlisting>
169 lxc-unshare -s "NETWORK|PID|MOUNT|UTSNAME" -M -H myhostname -i veth1 /bin/bash
170 </programlisting>
171
172 The resulting shell will have pid 1 and will see two network
173 interfaces (lo and veth1). The hostname will be "myhostname" and
174 /proc will have been remounted. ps output will show there are
175 no other processes in the namespace.
176 </para>
177 </refsect1>
178
179 &seealso;
180
181 </refentry>
182
183 <!-- Keep this comment at the end of the file
184 Local variables:
185 mode: sgml
186 sgml-omittag:t
187 sgml-shorttag:t
188 sgml-minimize-attributes:nil
189 sgml-always-quote-attributes:t
190 sgml-indent-step:2
191 sgml-indent-data:t
192 sgml-parent-document:nil
193 sgml-default-dtd-file:nil
194 sgml-exposed-tags:nil
195 sgml-local-catalogs:nil
196 sgml-local-ecat-files:nil
197 End:
198 -->