bracketing_commands(1) DG/UX B2 Security R4.12MU02 bracketing_commands(1)
NAME
bracketingcommands: establishusercaps, establishaugusercaps,
establishsystemcaps, getbaseexeccaps,
establishauguserexeccaps, establishsystemexeccaps,
restorebaseexeccaps, beginusersect, endusersect,
beginaugusersect, endaugusersect, beginsystemsect,
endsystemsect, beginuserexecsect, enduserexecsect,
beginauguserexecsect, endauguserexecsect,
beginsystemexecsect, endsystemexecsect - commands for
performing operation bracketing in shell scripts
SYNOPSIS
establishusercaps
establishaugusercaps optag
establishsystemcaps
getbaseexeccaps
establishauguserexeccaps optag
establishsystemexeccaps
restorebaseexeccaps capsetalias
beginusersect
endusersect capsetalias
beginaugusersect optag
endaugusersect capsetalias
beginsystemsect
endsystemsect capsetalias
beginuserexecsect capsetalias
enduserexecsect capsetalias
beginauguserexecsect optag capsetalias
endauguserexecsect capsetalias
beginsystemexecsect capsetalias
endsystemexecsect capsetalias
DESCRIPTION
The commands described here provide support for dealing with
operation bracketing in shell scripts. The commands fall into three
different families:
establishusercaps
establishaugusercaps
establishsystemcaps
This family is used in normal, everyday operations that do not
perform an exec() and where you know your context. They are
analogous to the family of library routines with the same names (see
bracketinglibrary(3)). These command manipulate the effective set
of the process and are used for operations like shell built-ins which
do not perform an exec().
getbaseexeccaps
establishauguserexeccaps
establishsystemexeccaps
restorebaseexeccaps
This family is used to bracket normal, everyday operations that
perform an exec() and where you know your context. These commands
manipulate the inheritable set of the process. If you need to use
this family of commands, you need to call getbaseexeccaps before
you do anything else. This will save the original inheritable set of
the process so you can restore it later. Whenever you come to an
augmented user or system operation, call the appropriate command.
This will change the inheritable set appropriately. When you next
encounter a user operation section (maybe right after the just-
bracketed operation), call restorebaseexeccaps and give it the
state you save in the getbaseexeccaps call. This will return the
process to the "user" state (this is why there's no
establish_user_exec_caps).
beginusersect
endusersect
beginaugusersect
endaugusersect
beginsystemsect
endsystemsect
This family is used when you need to do bracketing in a place in the
code where you do not know the context,such as a function that is
called from many different places. It is used to bracket operations
that do not perform an exec(). These commands are used in pairs
unlike the first two families above. The "begin" commands will save
the capability state before they establish the new cap state for
their type of operation. The "end" commands will restore the
capability state saved by the corresponding "begin" command. These
commands can be nested but it is up to the user to pass in the
appropriate cap state to the "end" calls.
beginuserexecsect
enduserexecsect
beginauguserexecsect
endauguserexecsect
beginsystemexecsect
endsystemexecsect
This family is used when you need to do bracketing in a place in the
code where you do no know the context, such as a function that is
called from many different places. It is used to bracket operations
that perform an exec(). These commands are used in pairs unlike the
first two families above. The "begin" commands will save the
capability state before they establish the new capability state for
their type of operation. The "end" commands will restore the
capability state saved by the corresponding "begin" command. These
commands can be nested, but it is up to the user to pass in the
appropriate capability state to the "end" calls.
establishusercaps
The establishusercaps command enables, in the effective set of the
calling process, the appropriate capabilities for performing user
operations. It attempts to enable all capabilities that are enabled
in the inheritable set of the calling process. All other
capabilities will be disabled in the effective set. If a capability
is enabled in the inheritable set but not in the permitted set of the
calling process, the capability will not be enabled in the effective
set but this will not cause an error condition.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Note. The establishusercaps command can only be used to bracket
user operations that are built-in shell operations (operations that
do not perform an exec()) because it manipulates the process'
effective capability set. To bracket user operations that perform an
exec(), use beginuserexecsect.
establishaugusercaps
The optag argument is listed in the op_tag table,
/etc/tcb/cap/optags. The optag argument defines a capability list
alias which specifies what capabilities the system will temporarily
grant to the process when performing the operation.
establishaugusercaps enbales, in the effective set of the calling
process, the appropriate capabilities for performing the augmented
user operation specified by optag. It attempts to enable all
capabilities that are enabled in the inheritable set of the calling
process plus the capabilities associated with optag. All other
capabilities will be disabled in the effective set. If a capability
is enabled in the inheritable set or is associated with optag but is
not enabled in the permitted set of the calling process, the
capability will not be enabled in the effective set but this will not
cause an error condition.
Example.
establishaugusercaps DGOTFOOBAR
Enables, in the effective set, all capabilities associated with the
DGOTFOOBAR optag, provided they are also in the permitted set.
File.
/etc/tcb/cap/op_tags Table of op_tags.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Note. The establishaugusercaps command can only be used to
bracket augmented user operations that are built-in shell operations
(operations that do not perform an exec()) because it manipulates the
process' effective capability set. If you want to bracket augmented
user operations that perform an exec() you must use
establishauguserexeccaps or beginauguserexecsect.
establishsystemcaps
The establishsystemcaps command enables, in the effective set of
the calling process, the appropriate capabilities for performing
system operations. It will enable all capabilities that are enabled
in the permitted set of the calling process. All other capabilities
will be disabled in the effective set.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Note. The establishsystemcaps command can only be used to bracket
system operations that are built-in shell operations (operations that
do not perform an exec()) because it manipulates the process'
effective capability set. If you want to bracket system operations
that perform an exec() you must use establishsystemexeccaps or
beginsystemexecsect.
getbaseexeccaps
The getbaseexeccaps command prints the alias representing the
inheritable capability set of the calling process to standard output.
Return Value. The alias representing the inheritable capability set
of the calling process is printed to standard output. Upon
successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
1 is returned.
Note. This command will not print anything to standard output on a
system on which the capability feature is not supported.
establishauguserexeccaps
The optag argument is listed in the op_tag table,
/etc/tcb/cap/optags. The optag argument defines a capability list
alias which specifies what capabilities the system will temporarily
grant to the process when performing the operation. The
establishauguserexeccaps command attempts to augment the
inheritable capability set of the calling process by enabling in it
the capabilities that are associated with optag. If a capability is
associated with optag but is not enabled in the permitted set of the
calling process, the capability will not be enabled in the
inheritable set but this will not cause an error condition.
Example.
establishauguserexeccaps DGOTFOOBAR
Enables, in the inheritable set, all capabilities associated with the
DGOTFOOBAR optag, provided they are also in the permitted set.
File.
/etc/tcb/cap/op_tags Table of op_tags.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of calling process
is unchanged.
Note. The establishauguserexeccaps command can only be used to
bracket augmented user operations that perform an exec() (e.g. a
shell command) because it manipulates the process' inheritable
capability set. If you want to bracket augmented user operations
that do not perform an exec() you must use establishaugusercaps or
beginaugusersect.
establishsystemexeccaps
The establishsystemexeccaps shell command will augment the
inheritable capability set of the calling process by enabling all
capabilities that are enabled in its permitted set.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Note. The establishsystemexeccaps command can only be used to
bracket system operations that perform an iexec() (e.g. a shell
command) because it manipulates the process' inheritable capability
set. If you want to bracket system operations that do not perform an
exec() you must use establishsystemcaps or beginsystemsect.
restorebaseexeccaps
The base capability state capsetalias is acquired by a call to
getbaseexeccaps. The restorebaseexeccaps command makes the
inheritable capability set of the calling process equal to the value
passed in as capsetalias. This value should be the result of a
previous call to getbaseexeccaps.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Note. The restorebaseexeccaps command will accept any capability
set alias as capsetalias but it is meant to only be used with the
value from a previous getbaseexeccaps call.
beginusersect
The beginusersect command prints an ASCII string representing the
effective capability set of the calling process to standard output.
It also enables, in the effective capability set of the calling
process, the appropriate capabilities for performing user operations.
It attempts to enable all capabilities that are enabled in the
inheritable set of the calling process. All other capabilities will
be disabled in the effective set. If a capability is enabled in the
inheritable set but not in the permitted set of the calling process,
the capability will not be enabled in the effective set but this will
not cause an error condition.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The beginusersect command can only be used to bracket user
operations that are built-in shell operations (operations that do not
perform an exec()) because it manipulates the process' effective
capability set. If you want to bracket user operations that perform
an exec() you must use beginuserexecsect.
The beginusersect command must be used instead of
establishusercaps when bracketing is being performed in a place
where you do not know your context (e.g. shell function). In these
cases you are going to want to restore the capability state that
existed before you entered that section of code upon exiting. Normal
in-line code should use establishusercaps.
The beginusersect command is meant to only be used in conjunction
with endusersect. You may nest calls to beginusersect and
endusersect and the capability state restored in the endusersect
call will be the state saved in the corresponding beginusersect
call.
endusersect
The capability set value capsetalias is obtained by the
corresponding call to beginusersect. The endusersect command
makes the effective capability set of the calling process equal to
the value passed in as capsetalias. This value should be the
result of the corresponding call to beginusersect.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. The endusersect command will accept any capability set
alias as capsetalias but it is meant to only be used with the value
from a previous beginusersect call.
The endusersect command is meant to only be used in conjunction
with beginusersect. You may nest calls to beginusersect and
endusersect and the capability state restored in the endusersect
call will be the state saved in the corresponding beginusersect
call.
beginaugusersect
The optag argument is listed in the op_tag table,
/etc/tcb/cap/optags. The optag argument defines a capability list
alias which specifies what capabilities the system will temporarily
grant to the process when performing the operation. The
beginaugusersect command prints an ASCII string representing the
effective capability set of the calling process to standard output.
It also enables, in the effective set of the calling process, the
appropriate capabilities for performing the augmented user operation
specified by optag. It attempts to enable all capabilities that are
enabled in the inheritable set of the calling process plus the
capability associated with optag. All other capabilities will be
disabled in the effective set. If a capability is enabled in the
inheritable set or associated with optag but not in the permitted
set of the calling process, the capability will not be enabled in the
effective set but this will not cause an error condition.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The beginaugusersect command can only be used to bracket augmented
user operations that are built-in shell operations (operations that
do not perform an exec()) because it manipulates the process'
effective capability set. If you want to bracket augmented user
operations that perform an exec() you must use
establishauguserexeccaps or beginauguserexecsect.
The beginaugusersect command must be used instead of
establishaugusercaps when bracketing is being performed in a place
where you do not know your context (e.g. shell function). In these
cases you are going to want to restore the capability state that
existed before you entered that section of code upon exiting. Normal
in-line code should use establishaugusercaps.
The beginaugusersect command is meant to only be used in
conjunction with endaugusersect. You may nest calls to
beginaugusersect and endaugusersect and the capability state
restored in the endaugusersect call will be the state saved in the
corresponding beginusersect call.
endaugusersect
The capability set value capsetalias is obtained by the
corresponding call to beginaugusersect. The endaugusersect
command makes the effective capability set of the calling process
equal to the value passed in as capsetalias. This value should be
the result of the corresponding call to beginaugusersect.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. The endaugusersect command will accept any capability set
alias as capsetalias but it is meant to only be used with the value
from a previous beginaugusersect call.
The endaugusersect command is meant to only be used in conjunction
with beginaugusersect. You may nest calls to beginaugusersect
and endaugusersect and the capability state restored in the
endaugusersect call will be the state saved in the corresponding
beginaugusersect call.
beginsystemsect
The beginsystemsect command prints an ASCII string representing the
effective capability set of the calling process to standard output.
It also enables, in the effective set of the calling process, the
appropriate capabilities for performing system operations. It will
enable all capabilities that are enabled in the permitted set of the
calling process. All other capabilities will be disabled in the
effective set.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The beginsystemsect command can only be used to bracket system
operations that are built-in shell operations (operations that do not
perform an exec()) because it manipulates the process' effective
capability set. If you want to bracket system operations that
perform an exec() you must use establishsystemexeccaps or
beginsystemexecsect.
The beginsystemsect command must be used instead of
establishsystemcaps when bracketing is being performed in a place
where you do not know your context (e.g. shell function). In these
cases you are going to want to restore the capability state that
existed before you entered that section of code upon exiting. Normal
in-line code should use establishsystemcaps.
The beginsystemsect command is meant to only be used in conjunction
with endsystemsect. You may nest calls to beginsystemsect and
endsystemsect and the capability state restored in the
endsystemsect call will be the state saved in the corresponding
beginsystemsect call.
endsystemsect
The capability set value capsetalias is obtained by the
corresponding call to beginsystemsect. The endsystemsect command
makes the effective capability set of the calling process equal to
the value passed in as capsetalias. This value should be the
result of the corresponding call to beginsystemsect.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. The endsystemsect command will accept any capability set
alias as capsetalias but it is meant to only be used with the value
from a previous beginsystemsect call.
The endsystemsect command is meant to only be used in conjunction
with beginsystemsect. You may nest calls to beginsystemsect and
endsystemsect and the capability state restored in the
endsystemsect call will be the state saved in the corresponding
beginsystemsect call.
beginuserexecsect
The capability set value capsetalias is obtained by the
corresponding call to getbaseexeccaps. The beginuserexecsect
command prints an ASCII string representing the inheritable
capability set of the calling process to standard output. It also
makes the inheritable capability set equal to the result of a
previous call to getbaseexeccaps (passed in as capsetalias), in
order to perform user operations. If beginuserexecsect is called
without a corresponding getbaseexeccaps call, it will return an
error.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The beginuserexecsect command can only be used to bracket user
operations that perform an exec() (e.g. a shell command) because it
manipulates the process' inheritable capability set. If you want to
bracket user operations that do not perform an exec() you must use
establishusercaps or beginusersect.
The beginuserexecsect command must be used when bracketing is
being performed in a place where you do not know your context (e.g.
shell function). In these cases you are going to want to restore the
capability state that existed before you entered that section of code
upon exiting.
The beginuserexecsect command is meant to only be used in
conjunction with enduserexecsect. You may nest calls to
beginuserexecsect and enduserexecsect and the capability state
restored in the enduserexecsect call will be the state saved in
the corresponding beginuserexecsect call.
enduserexecsect
The capability set value capsetalias is obtained by the
corresponding call to beginuserexecsect. The enduserexecsect
command makes the inheritable capability set of the calling process
equal to the value passed in as capsetalias. This value should be
the result of the corresponding call to beginuserexecsect.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. The enduserexecsect command will accept any capability set
alias as capsetalias but it is meant to only be used with the value
from a previous beginuserexecsect call.
The enduserexecsect command is meant to only be used in
conjunction with beginuserexecsect. You may nest calls to
beginuserexecsect and enduserexecsect and the capability state
restored in the enduserexecsect call will be the state saved in
the corresponding beginuserexecsect call.
beginauguserexecsect
The optag argument is listed in the op_tag table,
/etc/tcb/cap/optags. The optag defines a capability list alias
which specifies what capabilities the system will temporarily grant
to the process when performing the operation. The capability set
value capsetalias is obtained by the corresponding call to
getbaseexeccaps. The beginauguserexecsect command prints an
ASCII string representing the inheritable capability set of the
calling process to standard output. It also makes the inheritable
capability set equal to the result of a previous call to
getbaseexeccaps (passed in as capsetalias) plus the capabilities
that are associated with the specified optag.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The beginauguserexecsect command can only be used to bracket
augmented user operations that perform an exec() (e.g. a shell
command) because it manipulates the process' inheritable capability
set. If you want to bracket augmented user operations that do not
perform an exec() you must use establishaugusercaps or
beginaugusersect.
The beginauguserexecsect command must be used instead of
establishauguserexeccaps when bracketing is being performed in a
place where you do not know your context (e.g. shell function). In
these cases you are going to want to restore the capability state
that existed before you entered that section of code upon exiting.
Normal in-line code should use establishauguserexeccaps.
The beginauguserexecsect command is meant to only be used in
conjunction with endauguserexecsect. You may nest calls to
beginauguserexecsect and endauguserexecsect and the
capability state restored in the endauguserexecsect call will be
the state saved in the corresponding beginauguserexecsect call.
endauguserexecsect
The capability set value capsetalias is obtained by the
corresponding call to beginauguserexecsect. The
endauguserexecsect command makes the inheritable capability set
of the calling process equal to the value passed in as capsetalias.
This value should be the result of the corresponding call to
beginauguserexecsect.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. The endauguserexecsect command will accept any capability
set alias as capsetalias but it is meant to only be used with the
value from a previous beginauguserexecsect call.
The endauguserexecsect command is meant to only be used in
conjunction with beginauguserexecsect. You may nest calls to
beginauguserexecsect and endauguserexecsect and the
capability state restored in the endauguserexecsect call will be
the state saved in the corresponding beginauguserexecsect call.
beginsystemexecsect
The capability set value capsetalias is obtained by the
corresponding call to getbaseexeccaps. The beginsystemexecsect
command prints an ASCII string representing the inheritable
capability set of the calling process to standard output. It also
makes the inheritable capability set equal to the result of a
previous call to getbaseexeccaps (passed in as capsetalias) plus
the capability that are enabled in the permitted set.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The beginsystemexecsect command can only be used to bracket system
operations that perform an exec() (e.g. a shell command) because it
manipulates the process' inheritable capability set. If you want to
bracket system operations that do not perform an exec() you must use
establishsystemcaps or beginsystemsect.
The beginsystemexecsect command must be used instead of
establishsystemexeccaps when bracketing is being performed in a
place where you do not know your context (e.g. shell function). In
these cases you are going to want to restore the capability state
that existed before you entered that section of code upon exiting.
Normal in-line code should use establishsystemexeccaps.
The beginsystemexecsect command is meant to only be used in
conjunction with endsystemexecsect. You may nest calls to
beginsystemexecsect and endsystemsystemsect and the capability
state restored in the endsystemexecsect call will be the state
saved in the corresponding beginsystemexecsect call.
endsystemexecsect
The capability set value capsetalias is obtained by the
corresponding call to beginsystemexecsect. The
endsystemexecsect command makes the effective capability set of
the calling process equal to the value passed in as capsetalias.
This value should be the result of the corresponding call to
beginsystemexecsect.
Return Value. Upon successful completion or if the system does not
support the capability feature, a value of 0 is returned. Otherwise,
a value of 1 is returned and the capability state of the calling
process is unchanged.
Notes. The endsystemexecsect command will accept any capability
set alias as capsetalias but it is meant to only be used with the
value from a previous beginsystemexecsect call.
The endsystemexecsect command is meant to only be used in
conjunction with beginsystemexecsect. You may nest calls to
beginsystemexecsect and endsystemexecsect and the capability
state restored in the endsystemexecsect call will be the state
saved in the corresponding beginsystemexecsect call.
SEE ALSO
getcap(1), setcap(1), bracketinglibrary(3).
Licensed material--property of copyright holder(s)