su - Change the user ID associated with a session

Format

su [-] [-s][userid [arg ...]]

Description

su starts a new shell and lets you operate in it with the privileges of a superuser or another user.

If you do not specify a user ID, su changes your authorization to that of the superuser. The resulting MVS user ID can be any UID(0) user ID that is in the security product database. The security product returns the first UID(0) user ID that is found; this user ID can change over time as the cached information of the security product is updated.

If you specify a user ID, su changes your authorization to that of the specified user ID. The new environment is built and then a new session is initiated. The new session is run as a child shell of the shell issuing the su command.

Any arguments specified by arg are passed to the child shell, so must be valid invocation flags or arguments that are accepted by the child shell.

su performs these functions:

Obtains your user profile information. After validating that you have an OMVS segment in the user profile, the OMVS segment information is obtained.
Verifies authorization. If a user ID is not specified, you must have the appropriate authorization to obtain superuser authority. You must be permitted to the BPX.SUPERUSER resource in the FACILITY class.
If a user ID is specified, and you do not have read access to the SURROGAT class profile, BPX.SRV.uuuuuuuu (where uuuuuuuu is the MVS user ID associated with the target UID), you must enter the target user's password or password phrase when prompted. If a user ID is specified, and you have read access to the SURROGAT class profile for the target user, you can use the -s option, or press Enter at the password prompt.
Changes the group ID. If a user ID is specified, the group ID is changed to that of the specified user's default group GID.

If a user ID is specified, the supplementary group list is changed to that of the specified user.

If the change of group ID or supplemental group list fails, the su command issues a message and continues.
Changes the user ID. Your user ID might be changed to either the specified user ID or the superuser's user ID (UID 0).
- When a user ID is specified, your MVS identity changes to the specified user ID, changing your access authority for MVS data sets in addition to changing to the new user's UID.
- When a user ID is not specified, your MVS identity remains the same. This maintains your access authority to MVS data sets, while gaining superuser authority.
- If you are already running under UID 0 and BPX.DAEMON is defined, issuing su with no userid will result in your UID being switched to BPXROOT. If BPX.DAEMON is not defined, and you issue su with the userid while running under UID 0, your UID will remain set to 0. In both cases, access to the BPX.SUPERUSER resource in the FACILITY class will not be checked.
Sets up the shell environment. If the login shell ('-' flag) is specified, the OMVS segment of the new user is used to set up the shell environment, similar to user login processing. When a user ID is not specified, the new UID(0) user as found by the security product is used. This includes setting the SHELL, HOME, and LOGNAME environment variables. PATH is set to the system default (/bin), TERM is preserved from the current environment, and STEPLIB is set to "none". Other environment variables are not inherited by the new shell.
If the login shell is not specified, the OMVS segment of your user profile is used to set up the shell environment. The environment is set up to be as similar as possible to the environment of the shell issuing the su command. Existing values of HOME, LOGNAME, and PATH are preserved. If not set in the current shell environment, HOME and LOGNAME are set from the calling user's profile, and PATH is set to the system default (/bin). SHELL is set to calling user's profile value, or the default /bin/sh, if not defined.
Executes the new shell. If login shell ('-' flag) is specified, prepend '-' to the shell's name. This indicates that the shell should read its login startup files (for example, /bin/sh will read /etc/profile and $HOME/.profile). The new shell is initialized to run as a child process of the shell issuing the su command. If the su command is run from a restricted shell (such as a shell that was started with the -r option), you will exit from the restricted shell and leave the protection of the trusted environment.
Note:
1. The new shell is always run in a new address space, even if you have _BPX_SHAREAS=YES set.
2. If you use the OMVS interface when running a shell created by su, any attempt to execute TSO commands (PF6) results in the command running back in your TSO address space. When these TSO commands run, they run with your TSO identity, not the identity specified by su.
  If you are not using the OMVS interface (for example, you rlogin or telnet into the shell), you cannot use PF6 to execute a TSO command. As a result, there will be no TSO address space or identity. The alternative solution is to use tso -t or tsocmd, which allows you to run a TSO/E command with the current identity set by su.
3. For REXX execs, use the following line to change the effective UID of the current shell session without resulting in a new interactive shell session:
```
address 'SYSCALL' 'seteuid 0'
```

To restore the previous session, enter exit or press <EscChar-D> (where EscChar is normally the cent sign). If you use rlogin or telnet to enter the shell, you hold down the Ctrl key while you press D. This action ends the child shell initiated by the su command and returns you to the previous shell, user ID, and environment. For more information about exiting the shell environment, see Exiting the shell in z/OS UNIX System Services User's Guide.

Options

-: Starts the new shell as a login shell. Sets the shell variables SHELL, HOME, and LOGNAME according to the new user's profile, and prepends a '-' to the shell name to indicate that the shell should read its login profiles. When a user ID is not specified, the new UID(0) user as found by the security product is used.
-s: Does not prompt for password or password phrase. If a user ID is specified, you must have read access to the SURROGAT class profile, BPX.SRV.uuuuuuuu (where uuuuuuuu is the MVS™ userid associated with the target UID).

Examples

To switch to the admin user ID, but maintain the current user's shell environment:

su admin

To authorize a user to switch to another user without entering a password or password phrase, grant them RACF® SURROGAT authority:

RDEFINE SURROGAT BPX.SRV.ADMIN UACC(NONE)
PERMIT BPX.SRV.ADMIN CLASS(SURROGAT) ID(FRED) ACCESS(READ)
SETROPTS RACLIST(SURROGAT) REFRESH

Then, from Fred, issue:

su -s admin

To start a child shell with the login environment of the admin user ID:

su - admin

To run the /usr/lib/backupall script under the admin user ID and return to the parent shell environment when the script completes:

su admin /usr/lib/backupall

To run a remove shell command under the admin user ID and return to the parent shell environment when the command completes:

su admin -c "rm -rf /tmp/"

Usage notes

The new shell inherits the standard file descriptors from the su command, so commands can be piped to the stdin of the new shell and run under the new user.
If the OMVS NOECHO option is in effect, your password or password phrase is displayed.
Because su starts a new interactive shell, it should not be used from a batch interface such as BPXBATCH, unless you provide the commands to be executed under superuser via stdin to the su command.
After issuing su -s in the shell to switch to another user, the new user will not have the authority to issue any commands that require an implicit open() of a tty. This restriction includes calls which invoke the Binder (such as cp -X and c89) as well as explicit attempts at opening a file descriptor (such as cat /dev/fd2). An ICH408I message is written to the console to alert the user of the access violation.

Exit values

0

The command completed successfully.

1

The user is not authorized to obtain superuser authority.

2

Failure due to any of the following reasons:

Unable to execute the shell.
The OMVS segment of the user's profile cannot be found.
Unable to set up the superuser environment.

3

Failure due to any of the following reasons:

Incorrect command syntax.

Limitations

Only users who have RACF access permission to the superuser class can use su without specifying the user ID.

Portability

None. This command is an extension that comes with z/OS UNIX services.

Related information

sh, ISHELL