1 files changed, 120 insertions, 0 deletions
diff --git a/man/man5/subuid.5 b/man/man5/subuid.5
new file mode 100644
index 0000000..655fbb9
--- /dev/null
+++ b/man/man5/subuid.5
@@ -0,0 +1,120 @@
+'\" t
+.\"     Title: subuid
+.\"    Author: Eric Biederman
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 11/08/2022
+.\"    Manual: File Formats and Configuration Files
+.\"    Source: shadow-utils 4.13
+.\"  Language: English
+.\"
+.TH "SUBUID" "5" "11/08/2022" "shadow\-utils 4\&.13" "File Formats and Configuration"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+subuid \- the configuration for subordinate user ids
+.SH "DESCRIPTION"
+.PP
+Subuid authorizes a user id to map ranges of user ids from its namespace into child namespaces\&.
+.PP
+The delegation of the subordinate uids can be configured via the
+\fIsubid\fR
+field in
+/etc/nsswitch\&.conf
+file\&. Only one value can be set as the delegation source\&. Setting this field to
+\fIfiles\fR
+configures the delegation of uids to
+/etc/subuid\&. Setting any other value treats the delegation as a plugin following with a name of the form
+\fIlibsubid_$value\&.so\fR\&. If the value or plugin is missing, then the subordinate uid delegation falls back to
+\fIfiles\fR\&.
+.PP
+Note, that
+\fBuseradd\fR
+will only create entries in
+/etc/subuid
+if subid delegation is managed via subid files\&.
+.SH "LOCAL SUBORDINATE DELEGATION"
+.PP
+Each line in
+/etc/subuid
+contains a user name and a range of subordinate user ids that user is allowed to use\&. This is specified with three fields delimited by colons (\(lq:\(rq)\&. These fields are:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+login name or UID
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+numerical subordinate user ID
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+numerical subordinate user ID count
+.RE
+.PP
+This file specifies the user IDs that ordinary users can use, with the
+\fBnewuidmap\fR
+command, to configure uid mapping in a user namespace\&.
+.PP
+Multiple ranges may be specified per user\&.
+.PP
+When large number of entries (10000\-100000 or more) are defined in
+/etc/subuid, parsing performance penalty will become noticeable\&. In this case it is recommended to use UIDs instead of login names\&. Benchmarks have shown speed\-ups up to 20x\&.
+.SH "FILES"
+.PP
+/etc/subuid
+.RS 4
+Per user subordinate user IDs\&.
+.RE
+.PP
+/etc/subuid\-
+.RS 4
+Backup file for /etc/subuid\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBlogin.defs\fR(5),
+\fBnewgidmap\fR(1),
+\fBnewuidmap\fR(1),
+\fBnewusers\fR(1),
+\fBsubgid\fR(5),
+\fBuseradd\fR(8),
+\fBuserdel\fR(8),
+\fBusermod\fR(8),
+\fBuser_namespaces\fR(7)\&.