~ubuntu-branches/ubuntu/trusty/systemd/trusty

\fBchroot\fR(1), but more powerful since it fully virtualizes the file system hierarchy, as well as the process tree, the various IPC subsystems and the host and domain name\&.

.PP

\fBsystemd\-nspawn\fR

limits access to various kernel interfaces in the container to read\-only, such as

/sys,

/proc/sys

/sys/fs/selinux\&. Network interfaces and the system clock may not be changed from within the container\&. Device nodes may not be created\&. The host system cannot be rebooted and kernel modules may not be loaded from within the container\&.

.PP

Note that even though these security precautions are taken

\fBsystemd\-nspawn\fR

is not suitable for secure container setups\&. Many of the security features may be circumvented and are hence primarily useful to avoid accidental changes to the host system from the container\&. The intended use of this program is debugging and testing as well as building of packages, distributions and software involved with boot and systems management\&.

.PP

In contrast to

\fBchroot\fR(1)

\fBsystemd\-nspawn\fR

may be used to boot full Linux\-based operating systems in a container\&.

.PP

Use a tool like

\fByum\fR(8),

\fBdebootstrap\fR(8)

\fBpacman\fR(8)

to set up an OS directory tree suitable as file system hierarchy for

\fBsystemd\-nspawn\fR

containers\&.

.PP

Note that

\fBsystemd\-nspawn\fR

will mount file systems private to the container to

/dev,

/run

and similar\&. These will not be visible outside of the container, and their contents will be lost when the container exits\&.

.PP

Note that running two

\fBsystemd\-nspawn\fR

containers from the same directory tree will not make processes in them see each other\&. The PID namespace separation of the two containers is complete and the containers will share very few runtime objects except for the underlying file system\&. It is however possible to enter an existing container, see

Example 4

below\&.

.PP

\fBsystemd\-nspawn\fR

implements the

\m[blue]\fBContainer Interface\fR\m[]\&\s-2\u[1]\d\s+2

specification\&.

.SH "OPTIONS"

.PP

If option

\fB\-b\fR

is specified, the arguments are used as arguments for the init binary\&. Otherwise,

\fICOMMAND\fR

specifies the program to launch in the container, and the remaining arguments are used as arguments for this program\&. If

\fB\-b\fR

is not used and no arguments are specifed, a shell is launched in the container\&.

.PP

The following options are understood:

.PP

\fB\-h\fR, \fB\-\-help\fR

.RS 4

Prints a short help text and exits\&.

100

.RE

101

.PP

102

\fB\-\-version\fR

103

.RS 4

104

Prints a version string and exits\&.

105

.RE

106

.PP

107

\fB\-D\fR, \fB\-\-directory=\fR

108

.RS 4

109

Directory to use as file system root for the namespace container\&. If omitted the current directory will be used\&.

110

.RE

111

.PP

112

\fB\-b\fR, \fB\-\-boot\fR

113

.RS 4

114

Automatically search for an init binary and invoke it instead of a shell or a user supplied program\&. If this option is used, arguments specified on the command line are used as arguments for the init binary\&.

115

.RE

116

.PP

117

\fB\-u\fR, \fB\-\-user=\fR

118

.RS 4

119

Run the command under specified user, create home directory and cd into it\&. As rest of systemd\-nspawn, this is not the security feature and limits against accidental changes only\&.

120

.RE

121

.PP

122

\fB\-\-uuid=\fR

123

.RS 4

124

Set the specified uuid for the container\&. The init system will initialize

125

/etc/machine\-id

126

from this if this file is not set yet\&.

127

.RE

128

.PP

129

\fB\-C\fR, \fB\-\-controllers=\fR

130

.RS 4

131

Makes the container appear in other hierarchies than the name=systemd:/ one\&. Takes a comma\-separated list of controllers\&.

132

.RE

133

.PP

134

\fB\-\-private\-network\fR

135

.RS 4

136

Turn off networking in the container\&. This makes all network interfaces unavailable in the container, with the exception of the loopback device\&.

137

.RE

138

.PP

139

\fB\-\-read\-only\fR

140

.RS 4

141

Mount the root file system read only for the container\&.

142

.RE

143

.PP

144

\fB\-\-capability=\fR

145

.RS 4

146

List one or more additional capabilities to grant the container\&. Takes a comma separated list of capability names, see

147

\fBcapabilities\fR(7)

148

for more information\&. Note that the following capabilities will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE, CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT, CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL\&.

149

.RE

150

.PP

151

\fB\-\-link\-journal=\fR

152

.RS 4

153

Control whether the container\*(Aqs journal shall be made visible to the host system\&. If enabled allows viewing the container\*(Aqs journal files from the host (but not vice versa)\&. Takes one of

154

no,

155

host,

156

guest,

157

auto\&. If

158

no, the journal is not linked\&. If

159

host, the journal files are stored on the host file system (beneath

160

/var/log/journal/\fImachine\-id\fR) and the subdirectory is bind\-mounted into the container at the same location\&. If

161

guest, the journal files are stored on the guest file system (beneath

162

/var/log/journal/\fImachine\-id\fR) and the subdirectory is symlinked into the host at the same location\&. If

163

auto

164

(the default), and the right subdirectory of

165

/var/log/journal

166

exists, it will be bind mounted into the container\&. If the subdirectory doesn\*(Aqt exist, no linking is performed\&. Effectively, booting a container once with

167

guest

168

169

host

170

will link the journal persistently if further on the default of

171

auto

172

is used\&.

173

.RE

174

.PP

175

\fB\-j\fR

176

.RS 4

177

Equivalent to

178

\fB\-\-link\-journal=guest\fR\&.

179

.RE

180

.PP

181

\fB\-\-bind=\fR, \fB\-\-bind\-ro=\fR

182

.RS 4

183

Bind mount a file or directory from the host into the container\&. Either takes a path argument \-\- in which case the specified path will be mounted from the host to the same path in the container \-\-, or a colon\-separated pair of paths \-\- in which case the first specified path is the source in the host, and the second path is the destination in the container\&. The

184

\fB\-\-bind\-ro=\fR

185

option creates read\-only bind mount\&.

186

.RE

187

.SH "EXAMPLE 1"

188

.sp

189

.if n \{\

190

.RS 4

191

.\}

192

.nf

193

# yum \-y \-\-releasever=19 \-\-nogpg \-\-installroot=/srv/mycontainer \-\-disablerepo=\*(Aq*\*(Aq \-\-enablerepo=fedora install systemd passwd yum fedora\-release vim\-minimal

194

# systemd\-nspawn \-bD /srv/mycontainer

195

.fi

196

.if n \{\

197

.RE

198

.\}

199

.PP

200

This installs a minimal Fedora distribution into the directory

201

/srv/mycontainer/

202

and then boots an OS in a namespace container in it\&.

203

.SH "EXAMPLE 2"

204

.sp

205

.if n \{\

206

.RS 4

207

.\}

208

.nf

209

# debootstrap \-\-arch=amd64 unstable ~/debian\-tree/

210

# systemd\-nspawn \-D ~/debian\-tree/

211

.fi

212

.if n \{\

213

.RE

214

.\}

215

.PP

216

This installs a minimal Debian unstable distribution into the directory

217

~/debian\-tree/

218

and then spawns a shell in a namespace container in it\&.

219

.SH "EXAMPLE 3"

220

.sp

221

.if n \{\

222

.RS 4

223

.\}

224

.nf

225

# pacstrap \-c \-d ~/arch\-tree/ base

226

# systemd\-nspawn \-bD ~/arch\-tree/

227

.fi

228

.if n \{\

229

.RE

230

.\}

231

.PP

232

This installs a mimimal Arch Linux distribution into the directory

233

~/arch\-tree/

234

and then boots an OS in a namespace container in it\&.

235

.SH "EXAMPLE 4"

236

.PP

237

To enter the container, PID of one of the processes sharing the new namespaces must be used\&.

238

\fBsystemd\-nspawn\fR

239

prints the PID (as viewed from the outside) of the launched process, and it can be used to enter the container\&.

240

.sp

241

.if n \{\

242

.RS 4

243

.\}

244

.nf

245

# nsenter \-muinpt $PID

246

.fi

247

.if n \{\

248

.RE

249

.\}

250

.PP

251

\fBnsenter\fR(1)

252

is part of

253

\m[blue]\fButil\-linux\fR\m[]\&\s-2\u[2]\d\s+2\&. Kernel support for entering namespaces was added in Linux 3\&.8\&.

254

.SH "EXIT STATUS"

255

.PP

256

The exit code of the program executed in the container is returned\&.

257

.SH "SEE ALSO"

258

.PP

259

260

\fBsystemd\fR(1),

261

\fBchroot\fR(1),

262

\fBunshare\fR(1),

263

\fByum\fR(8),

264

\fBdebootstrap\fR(8),

265

\fBpacman\fR(8)

266

.SH "NOTES"

267

.IP " 1." 4

268

Container Interface

269

.RS 4

270

\%http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface

271

.RE

272

.IP " 2." 4

273

util-linux

274

.RS 4

275

\%https://github.com/karelzak/util-linux

276

.RE

Older »