summaryrefslogtreecommitdiff
path: root/docs/capng_change_id.3
diff options
context:
space:
mode:
Diffstat (limited to 'docs/capng_change_id.3')
-rw-r--r--docs/capng_change_id.344
1 files changed, 38 insertions, 6 deletions
diff --git a/docs/capng_change_id.3 b/docs/capng_change_id.3
index 3abfdd8..a13e51a 100644
--- a/docs/capng_change_id.3
+++ b/docs/capng_change_id.3
@@ -1,4 +1,4 @@
-.TH "CAPNG_CHANGE_ID" "3" "June 2009" "Red Hat" "Libcap-ng API"
+.TH "CAPNG_CHANGE_ID" "3" "Feb 2018" "Red Hat" "Libcap-ng API"
.SH NAME
capng_change_id \- change the credentials retaining capabilities
.SH "SYNOPSIS"
@@ -8,7 +8,9 @@ int capng_change_id(int uid, int gid, capng_flags_t flag);
.SH "DESCRIPTION"
-This function will change uid and gid to the ones given while retaining the capabilities previously specified in capng_update. It is not necessary and perhaps better if capng_apply has not been called prior to this function so that all necessary privileges are still intact. The caller is required to have CAP_SETPCAP capability still active before calling this function.
+This function will change uid and gid to the ones given while retaining the capabilities previously specified in capng_update. It is also possible to specify -1 for either the uid or gid in which case the function will not change the uid or gid and leave it "as is". This is useful if you just want the flag options to be applied (assuming the option doesn't require more privileges that you currently have).
+
+It is not necessary and perhaps better if capng_apply has not been called prior to this function so that all necessary privileges are still intact. The caller may be required to have CAP_SETPCAP capability still active before calling this function or capabilities cannot be changed.
This function also takes a flag parameter that helps to tailor the exact actions performed by the function to secure the environment. The option may be or'ed together. The legal values are:
@@ -18,15 +20,45 @@ This function also takes a flag parameter that helps to tailor the exact actions
Simply change uid and retain specified capabilities and that's all.
.TP
.B CAPNG_DROP_SUPP_GRP
-After changing id, remove and supplement groups that may come with the account.
+After changing id, remove any supplement groups that may still be in effect from the old uid.
+.TP
+.B CAPNG_INIT_SUPP_GRP
+After changing id, initialize any supplement groups that may come with the new account. If given with
+.B CAPNG_DROP_SUPP_GRP
+it will have no effect.
.TP
.B CAPNG_CLEAR_BOUNDING
-After changing the uid and gid, clear the bounding set regardless to the internal representation already setup.
+Clear the bounding set regardless to the internal representation already setup prior to changing the uid/gid.
+.TP
+.B CAPNG_CLEAR_AMBIENT
+Clear ambient capabilities regardless of the internal representation already setup prior to changing the uid/gid.
.RE
.SH "RETURN VALUE"
-This returns 0 on success and a negative number on failure. -1 means capng has not been initted properly, -2 means a failure requesting to keep capabilities across the uid change, -3 means that applying the intermediate capabilities failed, -4 means changing gid failed, -5 means dropping supplemental groups failed, -6 means changing the uid failed, -7 means dropping the ability to retain caps across a uid change failed, -8 means clearing the bounding set failed, -9 means dropping CAP_SETPCAP failed.
+This returns 0 on success and a negative number on failure.
+.RS
+.TP
+-1 means capng has not been initted properly
+.TP
+-2 means a failure requesting to keep capabilities across the uid change
+.TP
+-3 means that applying the intermediate capabilities failed
+.TP
+-4 means changing gid failed
+.TP
+-5 means dropping supplemental groups failed
+.TP
+-6 means changing the uid failed
+.TP
+-7 means dropping the ability to retain caps across a uid change failed
+.TP
+-8 means clearing the bounding set failed
+.TP
+-9 means dropping CAP_SETPCAP or ambient capabilities failed
+.TP
+-10 means initializing supplemental groups failed
+.RE
Note: the only safe action to do upon failure of this function is to probably exit. This is because you are likely in a situation with partial permissions and not what you intended.
@@ -35,7 +67,7 @@ Note: the only safe action to do upon failure of this function is to probably ex
.BR capng_update (3),
.BR capng_apply (3),
.BR prctl (2),
-.BR capabilities (7)
+.BR capabilities (7)
.SH AUTHOR
Steve Grubb