CLONE_NEWUTS documentation

CLONE_NEWUTS documentation

[Michael Kerrisk]

Serge, Eric,

Below is a patch to document the CLONE_NEWUTS flag that was
added in 2.6.19.

Could you please review and let me know of improvements
or inaccuracies?

By the way, does anyone know where the UTS name in the uname()
API comes from? My best guess is that it's from Unix Timesharing
System, but I don't know this for sure.

Cheers,

Michael

diff --git a/man2/clone.2 b/man2/clone.2
index 7212332..80f9caf 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -341,6 +340,33 @@ configuration option and that the process be privileged
 This flag can't be specified in conjunction with
 .BR CLONE_THREAD .
 .TP
+.BR CLONE_NEWUTS " (since Linux 2.6.19)"
+If
+.B CLONE_NEWUTS
+is set, then create the process in a new UTS namespace.
+If this flag is not set, then (as with
+.BR fork (2)),
+the process is created in the same UTS namespace as
+the calling process.
+This flag is intended for the implementation of control groups.
+
+A UTS namespace is the set of identifiers returned by
+.BR uname (2);
+among these, the domain name and the host name can be modified by
+.BR setdomainname (2)
+and
+.BR
+.BR sethostname (2),
+respectively.
+Changes made to these identifiers in one UTS namespace
+are visible to other processes in the same namespace,
+but are not visible to processes in other UTS namespaces.
+
+Use of this flag requires: a kernel configured with the
+.B CONFIG_UTS_NS
+configuration option and that the process be privileged
+.RB ( CAP_SYS_ADMIN ).
+.TP
 .BR CLONE_PARENT " (since Linux 2.3.12)"
 If
 .B CLONE_PARENT
@@ -723,15 +749,24 @@ but the kernel was not configured with the
 .B CONFIG_PID_NS
 option.
 .TP
+.B EINVAL
+.BR CLONE_NEWUTS
+was specified in
+.IR flags ,
+but the kernel was not configured with the
+.B CONFIG_UTS
+option.
+.TP
 .B ENOMEM
 Cannot allocate sufficient memory to allocate a task structure for the
 child, or to copy those parts of the caller's context that need to be
 copied.
 .TP
 .B EPERM
-.B CLONE_NEWNS
+.BR CLONE_NEWNS ,
+.BR CLONE_NEWPID ,
 or
-.B CLONE_NEWPID
+.BR CLONE_NEWUTS
 was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP).
 .TP
 .B EPERM

Re: CLONE_NEWUTS documentation

[Eric W. Biederman]

Michael Kerrisk <mtk.manpages@googlemail.com> writes:

> Serge, Eric,
>
> Below is a patch to document the CLONE_NEWUTS flag that was
> added in 2.6.19.
>
> Could you please review and let me know of improvements
> or inaccuracies?
>
> By the way, does anyone know where the UTS name in the uname()
> API comes from? My best guess is that it's from Unix Timesharing
> System, but I don't know this for sure.
>
> Cheers,
>
> Michael
>
> diff --git a/man2/clone.2 b/man2/clone.2
> index 7212332..80f9caf 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -341,6 +340,33 @@ configuration option and that the process be privileged
>  This flag can't be specified in conjunction with
>  .BR CLONE_THREAD .
>  .TP
> +.BR CLONE_NEWUTS " (since Linux 2.6.19)"
> +If
> +.B CLONE_NEWUTS
> +is set, then create the process in a new UTS namespace.
> +If this flag is not set, then (as with
> +.BR fork (2)),
> +the process is created in the same UTS namespace as
> +the calling process.

> +This flag is intended for the implementation of control groups.

See my previous email about containers vs control groups.

There are some corner cases with NFS usage in the kernel that still
need to be resolved but otherwise the uts namespace is considered correct
and complete.

Eric

Re: CLONE_NEWUTS documentation

[Michael Kerrisk]

Eric,

On Wed, Nov 19, 2008 at 8:21 PM, Eric W. Biederman
<ebiederm@xmission.com> wrote:
> Michael Kerrisk <mtk.manpages@googlemail.com> writes:
>
>> Serge, Eric,
>>
>> Below is a patch to document the CLONE_NEWUTS flag that was
>> added in 2.6.19.
>>
>> Could you please review and let me know of improvements
>> or inaccuracies?
>>
>> By the way, does anyone know where the UTS name in the uname()
>> API comes from? My best guess is that it's from Unix Timesharing
>> System, but I don't know this for sure.
>>
>> Cheers,
>>
>> Michael
>>
>> diff --git a/man2/clone.2 b/man2/clone.2
>> index 7212332..80f9caf 100644
>> --- a/man2/clone.2
>> +++ b/man2/clone.2
>> @@ -341,6 +340,33 @@ configuration option and that the process be privileged
>>  This flag can't be specified in conjunction with
>>  .BR CLONE_THREAD .
>>  .TP
>> +.BR CLONE_NEWUTS " (since Linux 2.6.19)"
>> +If
>> +.B CLONE_NEWUTS
>> +is set, then create the process in a new UTS namespace.
>> +If this flag is not set, then (as with
>> +.BR fork (2)),
>> +the process is created in the same UTS namespace as
>> +the calling process.
>
>> +This flag is intended for the implementation of control groups.
>
> See my previous email about containers vs control groups.

Otherwise, the documentation patch is okay?

> There are some corner cases with NFS usage in the kernel that still
> need to be resolved but otherwise the uts namespace is considered correct
> and complete.

Thanks for the info.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: CLONE_NEWUTS documentation

[Serge E. Hallyn]

Quoting Michael Kerrisk (mtk.manpages@googlemail.com):
> Serge, Eric,
> 
> Below is a patch to document the CLONE_NEWUTS flag that was
> added in 2.6.19.

Thanks for writing this.

> Could you please review and let me know of improvements
> or inaccuracies?
> 
> By the way, does anyone know where the UTS name in the uname()
> API comes from? My best guess is that it's from Unix Timesharing
> System, but I don't know this for sure.

That sounds plausible - I've wondered myself and even googled a
bit, but not found an answer.  I suppose we might need to ask
Linus, or check one of the git repos that goes back to the early
90s and see who created the struct.

> Cheers,
> 
> Michael
> 
> diff --git a/man2/clone.2 b/man2/clone.2
> index 7212332..80f9caf 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -341,6 +340,33 @@ configuration option and that the process be privileged
>  This flag can't be specified in conjunction with
>  .BR CLONE_THREAD .
>  .TP
> +.BR CLONE_NEWUTS " (since Linux 2.6.19)"
> +If
> +.B CLONE_NEWUTS
> +is set, then create the process in a new UTS namespace.

And the new UTS namespace will initially be identical as the
parent - same hostname and domainname.

> +If this flag is not set, then (as with
> +.BR fork (2)),
> +the process is created in the same UTS namespace as
> +the calling process.
> +This flag is intended for the implementation of control groups.

I'm not sure Eric was sufficiently clear - this flag is intended
for the implementation of virtual server functionality and maybe
checkpoint/restart (though I'm not sure any apps will care about
being able to reset the hostname on restart :)

It's not that you have to call it 'virtual server functionality',
just that 'control groups' is definately not right.

Maybe 'lightweight containers'?  "lightweight virtual servers'?

thanks,
-serge

Re: CLONE_NEWUTS documentation

[Michael Kerrisk]

Hi Serge,

On Sun, Nov 23, 2008 at 5:47 PM, Serge E. Hallyn <serge@hallyn.com> wrote:
> Quoting Michael Kerrisk (mtk.manpages@googlemail.com):
>> Serge, Eric,
>>
>> Below is a patch to document the CLONE_NEWUTS flag that was
>> added in 2.6.19.
>
> Thanks for writing this.

Thanks for replying ;-).

>> Could you please review and let me know of improvements
>> or inaccuracies?
>>
>> By the way, does anyone know where the UTS name in the uname()
>> API comes from? My best guess is that it's from Unix Timesharing
>> System, but I don't know this for sure.
>
> That sounds plausible - I've wondered myself and even googled a
> bit, but not found an answer.  I suppose we might need to ask
> Linus, or check one of the git repos that goes back to the early
> 90s and see who created the struct.

Oh -- "utsname" as a string (used in the uname() API) way predates Linux.

>> diff --git a/man2/clone.2 b/man2/clone.2
>> index 7212332..80f9caf 100644
>> --- a/man2/clone.2
>> +++ b/man2/clone.2
>> @@ -341,6 +340,33 @@ configuration option and that the process be privileged
>>  This flag can't be specified in conjunction with
>>  .BR CLONE_THREAD .
>>  .TP
>> +.BR CLONE_NEWUTS " (since Linux 2.6.19)"
>> +If
>> +.B CLONE_NEWUTS
>> +is set, then create the process in a new UTS namespace.
>
> And the new UTS namespace will initially be identical as the
> parent - same hostname and domainname.

Yes, it's a good idea to make that clear.  I've added some words to cover that.

>> +If this flag is not set, then (as with
>> +.BR fork (2)),
>> +the process is created in the same UTS namespace as
>> +the calling process.
>> +This flag is intended for the implementation of control groups.
>
> I'm not sure Eric was sufficiently clear - this flag is intended
> for the implementation of virtual server functionality and maybe
> checkpoint/restart (though I'm not sure any apps will care about
> being able to reset the hostname on restart :)
> It's not that you have to call it 'virtual server functionality',
> just that 'control groups' is definately not right.
>
> Maybe 'lightweight containers'?  "lightweight virtual servers'?

I just made it "containers".  Is that okay?

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: CLONE_NEWUTS documentation

[Serge E. Hallyn]

Quoting Michael Kerrisk (mtk.manpages@googlemail.com):
> > Maybe 'lightweight containers'?  "lightweight virtual servers'?
> 
> I just made it "containers".  Is that okay?

Yup.

thanks,
-serge

CLONE_NEWUTS documentation

[Michael Kerrisk]

Hello Serge,

In 2.6.19, your patch to add support for CLONE_NEWUTS was included.  Is
there there some for-userland-programmers documentation of this flag
somewhere?  Would you be able to send some documentation to me (ideally as
a patch to the clone.2 man page, but otherwise some plain text will do).

If this flag is also supported for unshare(), then could you please send me
a patch/text for that too?

Cheers,

Michael
-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.

Re: CLONE_NEWUTS documentation

[Eric W. Biederman]

Michael Kerrisk <mtk-manpages@gmx.net> writes:

> Hello Serge,
>
> In 2.6.19, your patch to add support for CLONE_NEWUTS was included.  Is
> there there some for-userland-programmers documentation of this flag
> somewhere?  Would you be able to send some documentation to me (ideally as
> a patch to the clone.2 man page, but otherwise some plain text will do).
>
> If this flag is also supported for unshare(), then could you please send me
> a patch/text for that too?

Again a short summary

The utsname namespace encapsulates the global kernel identification stored
in struct utsname returned from uname(2).

It is a very trivial namespace but it allows you to set multiple hostnames
and nis domainnames on the same machine.

Eric

Re: CLONE_NEWUTS documentation

[Michael Kerrisk]

Eric W. Biederman wrote:
> Michael Kerrisk <mtk-manpages@gmx.net> writes:
> 
>> Hello Serge,
>>
>> In 2.6.19, your patch to add support for CLONE_NEWUTS was included.  Is
>> there there some for-userland-programmers documentation of this flag
>> somewhere?  Would you be able to send some documentation to me (ideally as
>> a patch to the clone.2 man page, but otherwise some plain text will do).
>>
>> If this flag is also supported for unshare(), then could you please send me
>> a patch/text for that too?
> 
> Again a short summary
> 
> The utsname namespace encapsulates the global kernel identification stored
> in struct utsname returned from uname(2).
> 
> It is a very trivial namespace but it allows you to set multiple hostnames
> and nis domainnames on the same machine.

Thanks Eric.

And a further question: is CLONE_NEWUTS implemented for unshare()?

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.

Re: CLONE_NEWUTS documentation

[Serge E. Hallyn]

Quoting Michael Kerrisk (mtk-manpages@gmx.net):
> 
> 
> Eric W. Biederman wrote:
> > Michael Kerrisk <mtk-manpages@gmx.net> writes:
> > 
> >> Hello Serge,
> >>
> >> In 2.6.19, your patch to add support for CLONE_NEWUTS was included.  Is
> >> there there some for-userland-programmers documentation of this flag
> >> somewhere?  Would you be able to send some documentation to me (ideally as
> >> a patch to the clone.2 man page, but otherwise some plain text will do).
> >>
> >> If this flag is also supported for unshare(), then could you please send me
> >> a patch/text for that too?
> > 
> > Again a short summary
> > 
> > The utsname namespace encapsulates the global kernel identification stored
> > in struct utsname returned from uname(2).
> > 
> > It is a very trivial namespace but it allows you to set multiple hostnames
> > and nis domainnames on the same machine.
> 
> Thanks Eric.
> 
> And a further question: is CLONE_NEWUTS implemented for unshare()?

Yes, it is.  And unlike CLONE_FS but like CONE_NEWNS, it has the same
meaning for unshare as for clone.

thanks,
-serge