CLONE_NEWUTS documentation

PATCH Michael Kerrisk 4 participants 6 messages Nov 19, 2008 – Nov 24, 2008 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Michael Kerrisk

author

2008-11-19 19:11 UTC #0 lore raw

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

man2/clone.2 +38 -2

index 7212332..80f9caf 100644
@@ -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

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Eric W. Biederman

2008-11-20 01:21 UTC #1 lore raw

Quoted 24 lines · 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
man2/clone.2 +0 -0
index 7212332..80f9caf 100644
@@ -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

man2/clone.2 configuration option and that the process be privileged · line 352

Quoted 10 lines

man2/clone.2 +9 -0

+.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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Michael Kerrisk

author

2008-11-20 11:51 UTC #2 lore raw

Eric,

Quoted 35 lines · Eric W. Biederman

Quoted 32 lines · 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
man2/clone.2 +8 -0
index 7212332..80f9caf 100644
@@ -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.

Quoted 3 lines

man2/clone.2 configuration option and that the process be privileged · line 351
Quoted 1 line
man2/clone.2 +1 -0
+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?

Quoted 3 lines

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

Signature · 5 lines

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

Serge E. Hallyn

2008-11-23 22:46 UTC #3 lore raw

In reply to Michael Kerrisk

Quoted 4 lines · Michael Kerrisk

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

Thanks for writing this.

Quoted 6 lines

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.

Quoted 9 lines

Cheers,
Michael
man2/clone.2 +0 -0
index 7212332..80f9caf 100644

man2/clone.2 configuration option and that the process be privileged · line 346

Quoted 7 lines

man2/clone.2 +4 -0

@@ -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.

man2/clone.2 configuration option and that the process be privileged · line 351

Quoted 5 lines

man2/clone.2 +5 -0

+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

Michael Kerrisk

author

2008-11-24 23:14 UTC #4 lore raw

Hi Serge,

Quoted 7 lines · Serge E. Hallyn

Quoted 4 lines · Michael Kerrisk
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 ;-).

Quoted 11 lines

Quoted 6 lines
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.

Quoted 7 lines

man2/clone.2 +0 -0

index 7212332..80f9caf 100644
@@ -341,6 +340,33 @@ configuration option and that the process be privileged
 This flag can't be specified in conjunction with
 .BR CLONE_THREAD .

Quoted 8 lines

man2/clone.2 configuration option and that the process be privileged · line 346
Quoted 5 lines
man2/clone.2 +4 -0
 .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.

Quoted 13 lines

man2/clone.2 configuration option and that the process be privileged · line 351
Quoted 5 lines
man2/clone.2 +5 -0
+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.

Quoted 1 line

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

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

Cheers,

Michael

Signature · 9 lines

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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Serge E. Hallyn

2008-11-24 23:45 UTC #5 lore raw

Quoted 3 lines · Michael Kerrisk

Quoted 1 line
Maybe 'lightweight containers'? "lightweight virtual servers'?
I just made it "containers". Is that okay?

Yup.

thanks,
-serge
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html