* [PATCH 1/2] setns.2: Initial man page
@ 2011-05-30 3:16 Eric W. Biederman
[not found] ` <m1r57gj2sh.fsf-+imSwln9KH6u2/kzUuoCbdi2O/JbrIOy@public.gmane.org>
0 siblings, 1 reply; 4+ messages in thread
From: Eric W. Biederman @ 2011-05-30 3:16 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
Signed-off-by: Eric W. Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
---
man2/setns.2 | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 88 insertions(+), 0 deletions(-)
create mode 100644 man2/setns.2
diff --git a/man2/setns.2 b/man2/setns.2
new file mode 100644
index 0000000..8b48e14
--- /dev/null
+++ b/man2/setns.2
@@ -0,0 +1,88 @@
+.\" Copyright (C) 2011, Eric Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
+.\" Licensed under the GPLv2
+.\"
+.TH SETNS 2 2011-05-28 "Linux" "Linux Programmer's Manual"
+.SH NAME
+setns \- reassociate parts of the process execution context
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
+.B #include <sched.h>
+.sp
+.BI "int setns(int " fd ", int " nstype );
+.fi
+.SH DESCRIPTION
+Given a file descriptor referring to a namespace reassociate the
+current process with that namespace.
+
+The
+.I nstype
+argument is an enumeration that specifies which type of namespace
+the current process may be reassociated with. This argument can
+have one of the following values:
+
+.TP
+.BR 0
+Allow any namespace to be joined.
+.TP
+.BR CLONE_NEWIPC
+Only allow joining an ipc namespace.
+.TP
+.BR CLONE_NEWNET
+Only allow joining a network namespace.
+.TP
+.BR CLONE_NEWUTS
+Only allow joining a uts namespace.
+.PP
+If
+.I flags
+is specified as zero, then
+.BR setns ()
+is a no-op;
+no changes are made to the calling process's execution context.
+.SH RETURN VALUE
+On success, zero returned.
+On failure, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.TP
+.B EBADF
+A bad file descriptor was passed to setns.
+
+.TP
+.B EINVAL
+A file descriptor that does not match the specified nstype.
+
+Attempting to change the mount namespace and the filesystem
+is shared between multiple tasks.
+
+.TP
+.B ENOMEM
+Cannot allocate sufficient memory to change the specified namespace.
+
+.TP
+.B EPERM
+The calling process did not have the required privileges for this operation.
+.SH VERSIONS
+The
+.BR setns ()
+system call first appeared in Linux in kernel 3.0
+.SH CONFORMING TO
+The
+.BR setns ()
+system call is Linux-specific.
+.SH NOTES
+Not all of the process attributes that can be shared when
+a new process is created using
+.BR clone (2)
+can be changed using
+.BR setns ().
+.SH BUGS
+The pid namespace and the mount namespace are not currently supported.
+.SH SEE ALSO
+.BR clone (2),
+.BR fork (2),
+.BR vfork (2),
+.BR setns(2)
--
1.7.5.1.217.g4e3aa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [PATCH 2/2] proc.5: Document /proc/[pid]/ns/
[not found] ` <m1r57gj2sh.fsf-+imSwln9KH6u2/kzUuoCbdi2O/JbrIOy@public.gmane.org>
@ 2011-05-30 3:17 ` Eric W. Biederman
[not found] ` <m1lixoj2qq.fsf-+imSwln9KH6u2/kzUuoCbdi2O/JbrIOy@public.gmane.org>
2011-09-15 4:13 ` [PATCH 1/2] setns.2: Initial man page Michael Kerrisk
1 sibling, 1 reply; 4+ messages in thread
From: Eric W. Biederman @ 2011-05-30 3:17 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
Signed-off-by: Eric W. Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
---
man5/proc.5 | 44 ++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 44 insertions(+), 0 deletions(-)
diff --git a/man5/proc.5 b/man5/proc.5
index 7c5ca4e..7ff82c4 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -476,6 +476,50 @@ information via this field.
.IP
This file is only readable by the owner of the process.
.TP
+.IR /proc/[pid]/ns/ " (since Linux 3.0)"
+This is a subdirectory containing one entry for each namespace that
+supports being manipulated by
+.BR setns(2).
+.TP
+.IR /proc/[pid]/ns/ipc " (since Linux 3.0)"
+Bind mounting this file to somewhere else in the filesystem keeps
+the ipc namespace of the process specified by
+.I pid
+alive even if all of the processes currently in that ipc namespace exit.
+
+Opening this file returnes a file handle for the ipc namespace
+of the process specified by
+.I pid,
+that keeps the ipc namespace alive while the file is open and that can
+be passed to
+.BR setns(2).
+.TP
+.IR /proc/[pid]/ns/net " (since Linux 3.0)"
+Bind mounting this file to somewhere else in the filesystem keeps
+the network namespace of the process specified by
+.I pid
+alive even if all of the processes currently in that network namespace exit.
+
+Opening this file returnes a file handle for the network namespace
+of the process specified by
+.I pid,
+that keeps the network namespace alive while the file is open and that can
+be passed to
+.BR setns(2).
+.TP
+.IR /proc/[pid]/ns/uts " (since Linux 3.0)"
+Bind mounting this file to somewhere else in the filesystem keeps
+the uts namespace of the process specified by
+.I pid
+alive even if all of the processes currently in that uts namespace exit.
+
+Opening this file returnes a file handle for the uts namespace
+of the process specified by
+.I pid,
+that keeps the uts namespace alive while the file is open and that can
+be passed to
+.BR setns(2).
+.TP
.IR /proc/[pid]/numa_maps " (since Linux 2.6.14)"
See
.BR numa (7).
--
1.7.5.1.217.g4e3aa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH 2/2] proc.5: Document /proc/[pid]/ns/
[not found] ` <m1lixoj2qq.fsf-+imSwln9KH6u2/kzUuoCbdi2O/JbrIOy@public.gmane.org>
@ 2011-09-09 13:47 ` Michael Kerrisk
0 siblings, 0 replies; 4+ messages in thread
From: Michael Kerrisk @ 2011-09-09 13:47 UTC (permalink / raw)
To: Eric W. Biederman; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
Hello Eric,
On Mon, May 30, 2011 at 5:17 AM, Eric W. Biederman
<ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org> wrote:
>
> Signed-off-by: Eric W. Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
> ---
> man5/proc.5 | 44 ++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 44 insertions(+), 0 deletions(-)
>
> diff --git a/man5/proc.5 b/man5/proc.5
> index 7c5ca4e..7ff82c4 100644
> --- a/man5/proc.5
> +++ b/man5/proc.5
> @@ -476,6 +476,50 @@ information via this field.
> .IP
> This file is only readable by the owner of the process.
> .TP
> +.IR /proc/[pid]/ns/ " (since Linux 3.0)"
> +This is a subdirectory containing one entry for each namespace that
> +supports being manipulated by
> +.BR setns(2).
> +.TP
> +.IR /proc/[pid]/ns/ipc " (since Linux 3.0)"
> +Bind mounting this file to somewhere else in the filesystem keeps
> +the ipc namespace of the process specified by
> +.I pid
> +alive even if all of the processes currently in that ipc namespace exit.
> +
> +Opening this file returnes a file handle for the ipc namespace
> +of the process specified by
> +.I pid,
> +that keeps the ipc namespace alive while the file is open and that can
> +be passed to
> +.BR setns(2).
> +.TP
> +.IR /proc/[pid]/ns/net " (since Linux 3.0)"
> +Bind mounting this file to somewhere else in the filesystem keeps
> +the network namespace of the process specified by
> +.I pid
> +alive even if all of the processes currently in that network namespace exit.
> +
> +Opening this file returnes a file handle for the network namespace
> +of the process specified by
> +.I pid,
> +that keeps the network namespace alive while the file is open and that can
> +be passed to
> +.BR setns(2).
> +.TP
> +.IR /proc/[pid]/ns/uts " (since Linux 3.0)"
> +Bind mounting this file to somewhere else in the filesystem keeps
> +the uts namespace of the process specified by
> +.I pid
> +alive even if all of the processes currently in that uts namespace exit.
> +
> +Opening this file returnes a file handle for the uts namespace
> +of the process specified by
> +.I pid,
> +that keeps the uts namespace alive while the file is open and that can
> +be passed to
> +.BR setns(2).
> +.TP
> .IR /proc/[pid]/numa_maps " (since Linux 2.6.14)"
> See
> .BR numa (7).
Thanks for that. I tweaked the text somewhat. COuld you review the
following text (actual patch shown further down):
/proc/[pid]/ns/ (since Linux 3.0)
This is a subdirectory containing one entry for each
namespace that supports being manipulated by setns(2).
For information about namespaces, see clone(2).
/proc/[pid]/ns/ipc (since Linux 3.0)
Bind mounting this file (see mount(2)) to somewhere else
in the filesystem keeps the IPC namespace of the process
specified by pid alive even if all processes currently
in the namespace terminate.
Opening this file returns a file handle for the IPC
namespace of the process specified by pid. As long as
this file descriptor remains open, the IPC namespace
will remain alive, even if all processes in the names-
pace terminate. The file descriptor can be passed to
setns(2).
/proc/[pid]/ns/net (since Linux 3.0)
Bind mounting this file (see mount(2)) to somewhere else
in the filesystem keeps the network namespace of the
process specified by pid alive even if all processes in
the namespace terminate.
Opening this file returns a file handle for the network
namespace of the process specified by pid. As long as
this file descriptor remains open, the network namespace
will remain alive, even if all processes in the names-
pace terminate. The file descriptor can be passed to
setns(2).
/proc/[pid]/ns/uts (since Linux 3.0)
Bind mounting this file (see mount(2)) to somewhere else
in the filesystem keeps the UTS namespace of the process
specified by pid alive even if all processes currently
in the namespace terminate.
Opening this file returns a file handle for the UTS
namespace of the process specified by pid. As long as
this file descriptor remains open, the UTS namespace
will remain alive, even if all processes in the names-
pace terminate. The file descriptor can be passed to
setns(2).
Cheers,
Michael
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -58,7 +58,7 @@
.\" to see what information could be imported from that file
.\" into this file.
.\"
-.TH PROC 5 2010-10-30 "Linux" "Linux Programmer's Manual"
+.TH PROC 5 2011-09-08 "Linux" "Linux Programmer's Manual"
.SH NAME
proc \- process information pseudo-file system
.SH DESCRIPTION
@@ -476,6 +476,64 @@ information via this field.
.IP
This file is only readable by the owner of the process.
.TP
+.IR /proc/[pid]/ns/ " (since Linux 3.0)"
+This is a subdirectory containing one entry for each namespace that
+supports being manipulated by
+.BR setns (2).
+For information about namespaces, see
+.BR clone (2).
+.TP
+.IR /proc/[pid]/ns/ipc " (since Linux 3.0)"
+Bind mounting this file (see
+.BR mount (2))
+to somewhere else in the filesystem keeps
+the IPC namespace of the process specified by
+.I pid
+alive even if all processes currently in the namespace terminate.
+
+Opening this file returns a file handle for the IPC namespace
+of the process specified by
+.IR pid .
+As long as this file descriptor remains open,
+the IPC namespace will remain alive,
+even if all processes in the namespace terminate.
+The file descriptor can be passed to
+.BR setns (2).
+.TP
+.IR /proc/[pid]/ns/net " (since Linux 3.0)"
+Bind mounting this file (see
+.BR mount (2))
+to somewhere else in the filesystem keeps
+the network namespace of the process specified by
+.I pid
+alive even if all processes in the namespace terminate.
+
+Opening this file returns a file handle for the network namespace
+of the process specified by
+.IR pid .
+As long as this file descriptor remains open,
+the network namespace will remain alive,
+even if all processes in the namespace terminate.
+The file descriptor can be passed to
+.BR setns (2).
+.TP
+.IR /proc/[pid]/ns/uts " (since Linux 3.0)"
+Bind mounting this file (see
+.BR mount (2))
+to somewhere else in the filesystem keeps
+the UTS namespace of the process specified by
+.I pid
+alive even if all processes currently in the namespace terminate.
+
+Opening this file returns a file handle for the UTS namespace
+of the process specified by
+.IR pid .
+As long as this file descriptor remains open,
+the UTS namespace will remain alive,
+even if all processes in the namespace terminate.
+The file descriptor can be passed to
+.BR setns (2).
+.TP
.IR /proc/[pid]/numa_maps " (since Linux 2.6.14)"
See
.BR numa (7).
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH 1/2] setns.2: Initial man page
[not found] ` <m1r57gj2sh.fsf-+imSwln9KH6u2/kzUuoCbdi2O/JbrIOy@public.gmane.org>
2011-05-30 3:17 ` [PATCH 2/2] proc.5: Document /proc/[pid]/ns/ Eric W. Biederman
@ 2011-09-15 4:13 ` Michael Kerrisk
1 sibling, 0 replies; 4+ messages in thread
From: Michael Kerrisk @ 2011-09-15 4:13 UTC (permalink / raw)
To: Eric W. Biederman; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA, Serge E. Hallyn
Hello Eric,
See below.
On Mon, May 30, 2011 at 5:16 AM, Eric W. Biederman
<ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org> wrote:
>
> Signed-off-by: Eric W. Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
> ---
> man2/setns.2 | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 88 insertions(+), 0 deletions(-)
> create mode 100644 man2/setns.2
>
> diff --git a/man2/setns.2 b/man2/setns.2
> new file mode 100644
> index 0000000..8b48e14
> --- /dev/null
> +++ b/man2/setns.2
> @@ -0,0 +1,88 @@
> +.\" Copyright (C) 2011, Eric Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
> +.\" Licensed under the GPLv2
> +.\"
> +.TH SETNS 2 2011-05-28 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +setns \- reassociate parts of the process execution context
> +.SH SYNOPSIS
> +.nf
> +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
> +.B #include <sched.h>
> +.sp
> +.BI "int setns(int " fd ", int " nstype );
> +.fi
> +.SH DESCRIPTION
> +Given a file descriptor referring to a namespace reassociate the
> +current process with that namespace.
> +
> +The
> +.I nstype
> +argument is an enumeration that specifies which type of namespace
> +the current process may be reassociated with. This argument can
> +have one of the following values:
> +
> +.TP
> +.BR 0
> +Allow any namespace to be joined.
> +.TP
> +.BR CLONE_NEWIPC
> +Only allow joining an ipc namespace.
> +.TP
> +.BR CLONE_NEWNET
> +Only allow joining a network namespace.
> +.TP
> +.BR CLONE_NEWUTS
> +Only allow joining a uts namespace.
> +.PP
> +If
> +.I flags
> +is specified as zero, then
> +.BR setns ()
> +is a no-op;
> +no changes are made to the calling process's execution context.
> +.SH RETURN VALUE
> +On success, zero returned.
> +On failure, \-1 is returned and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.TP
> +.B EBADF
> +A bad file descriptor was passed to setns.
> +
> +.TP
> +.B EINVAL
> +A file descriptor that does not match the specified nstype.
> +
> +Attempting to change the mount namespace and the filesystem
> +is shared between multiple tasks.
> +
> +.TP
> +.B ENOMEM
> +Cannot allocate sufficient memory to change the specified namespace.
> +
> +.TP
> +.B EPERM
> +The calling process did not have the required privileges for this operation.
> +.SH VERSIONS
> +The
> +.BR setns ()
> +system call first appeared in Linux in kernel 3.0
> +.SH CONFORMING TO
> +The
> +.BR setns ()
> +system call is Linux-specific.
> +.SH NOTES
> +Not all of the process attributes that can be shared when
> +a new process is created using
> +.BR clone (2)
> +can be changed using
> +.BR setns ().
> +.SH BUGS
> +The pid namespace and the mount namespace are not currently supported.
> +.SH SEE ALSO
> +.BR clone (2),
> +.BR fork (2),
> +.BR vfork (2),
> +.BR setns(2)
> --
> 1.7.5.1.217.g4e3aa
I made various edits to the page, some after out F2F conversations.
Could you please comment on the new version below?
Note: we talked a couple of times about this piece of text under the
EINVAL error.
Attempted to change the mount namespace, but the filesystem
is shared between multiple tasks.
As I understand it, this refers to interactions between the mount
namespace and file system namespace. However, as noted in the man
page, setns() does not support CLONE_NEWNS. Furthermore, I can see no
path in the setns() that generates EINVAL and involves CLONE_NEWNS.
So,I removed that text. Please let me know if that's wrong.
Cheers,
Michael
.\" Copyright (C) 2011, Eric Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
.\" Licensed under the GPLv2
.\"
.TH SETNS 2 2011-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
setns \- reassociate process with a namespace
.SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sched.h>
.sp
.BI "int setns(int " fd ", int " nstype );
.fi
.SH DESCRIPTION
Given a file descriptor referring to a namespace,
reassociate the calling process with that namespace.
The
.I fd
argument is a file descriptor referring to one of the namespace entries in a
.I /proc/[pid]/ns/
directory; see
.BR proc (5)
for further information on
.IR /proc/[pid]/ns/ .
The calling process will be reassociated with the corresponding namespace,
subject to any constraints imposed by the
.I nstype
argument.
The
.I nstype
argument specifies which type of namespace
the calling process may be reassociated with.
This argument can have one of the following values:
.TP
.BR 0
Allow any type of namespace to be joined.
.TP
.BR CLONE_NEWIPC
.I fd
must refer to an IPC namespace.
.TP
.BR CLONE_NEWNET
.I fd
must refer to a network namespace.
.TP
.BR CLONE_NEWUTS
.I fd
must refer to a UTS namespace.
.PP
Specifying
.I nstype
as 0 suffices if the caller knows (or does not care)
what type of namespace is referred to by
.IR fd .
Specifying a nonzero value for
.I nstype
is useful if the caller does not know what type of namespace is referred to by
.IR fd
and wants to ensure that the namespace is of a particular type.
(The caller might not know the type of the namespace referred to by
.IR fd
if the file descriptor was opened by another process and, for example,
passed to the caller via a UNIX domain socket.)
.SH RETURN VALUE
On success,
.IR setns ()
returns 0.
On failure, \-1 is returned and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EBADF
.I fd
is not a valid file descriptor.
.TP
.B EINVAL
.I fd
refers to a namespace whose type does not match that specified in
.IR nstype .
.TP
.B ENOMEM
Cannot allocate sufficient memory to change the specified namespace.
.TP
.B EPERM
The calling process did not have the required privilege
.RB ( CAP_SYS_ADMIN )
for this operation.
.SH VERSIONS
The
.BR setns ()
system call first appeared in Linux in kernel 3.0
.SH CONFORMING TO
The
.BR setns ()
system call is Linux-specific.
.SH NOTES
Not all of the process attributes that can be shared when
a new process is created using
.BR clone (2)
can be changed using
.BR setns ().
.SH BUGS
The PID namespace and the mount namespace are not currently supported.
(See the descriptions of
.BR CLONE_NEWPID
and
.BR CLONE_NEWNS
in
.BR clone (2).)
.SH SEE ALSO
.BR clone (2),
.BR fork (2),
.BR vfork (2),
.BR proc (5),
.BR unix (7)
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2011-09-15 4:13 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-05-30 3:16 [PATCH 1/2] setns.2: Initial man page Eric W. Biederman
[not found] ` <m1r57gj2sh.fsf-+imSwln9KH6u2/kzUuoCbdi2O/JbrIOy@public.gmane.org>
2011-05-30 3:17 ` [PATCH 2/2] proc.5: Document /proc/[pid]/ns/ Eric W. Biederman
[not found] ` <m1lixoj2qq.fsf-+imSwln9KH6u2/kzUuoCbdi2O/JbrIOy@public.gmane.org>
2011-09-09 13:47 ` Michael Kerrisk
2011-09-15 4:13 ` [PATCH 1/2] setns.2: Initial man page Michael Kerrisk
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.