Go to main content

Reference for Oracle Solaris Cluster 4.4

Exit Print View

Updated: August 2018
 
 

scha_check_app_user (8HA)

Name

scha_check_app_user - fetch application username and check ownership and permissions

Synopsis

scha_check_app_user [-R resource] [-U username] [-Z 
     zoneclustername] cmd-path

Description

The scha_check_app_user command obtains the configured application user name for use by a resource that is under the control of the Resource Group Manager (RGM). It also checks ownership and permissions on an executable file specified by cmd-path. This executable file is typically an application program that is intended to be executed by a method or monitor of the resource, using a wrapper such as su(8) to set the user ID to the configured user. The resource method or monitor invokes scha_check_app_user prior to execution of the application program. Depending on the output of scha_check_app_user, the method or monitor may return an error or output a warning message if security-related problems are detected.

The scha_check_app_user command writes the name of the configured user to standard output (file descriptor 1) and writes any security warnings or error messages to standard error (file descriptor 2). The exit code indicates whether configured security policy allows the command to be executed. If the exit code is 0, the caller can attempt to execute the command as the application user. If the exit code is non-zero, the caller should not attempt to execute the command as the application user, and should return an error.

Usage

A script that invokes scha_check_app_user can use the command's output to determine the following:

  • What user ID should execute the command

  • Whether to permit command execution or throw an error

  • What error or warning message to pass back to the user if a security issue is found

The scha_check_app_user command works with the Resource_security and Application_user properties described in the r_properties(7) man page.

The behavior of the scha_check_app_user command depends on the setting of the Resource_security property. The Resource_security property might have a different value in the global cluster and in each zone cluster. The value of Resource_security that is used by scha_check_app_user is the value of that property in the cluster in which the command is executed.

The scha_check_app_user command is meant to be invoked in the same context in which the application program is going to be executed. For example, if the application program executes in the global zone, then scha_check_app_user should also execute in the global zone.

The normal use case is one of the following:

  • The resource and its resource group are configured in the global cluster, and the scha_check_app_user program is executing in the global cluster.

  • The resource and its resource group are configured in a zone cluster, and the scha_check_app_user program is executing in a zone of that zone cluster.

In both use cases, there is no need to specify the –Z zoneclustername option on the command.

The –Z zoneclustername option is used when the application program is to be executed in the global zone but is associated with a resource in a zone cluster. This is not usually required, but might be necessary for a resource type that has the Global_zone property set to TRUE. For more information, see rt_properties(7).

See the OPTIONS section for details about the use of –Z and the interaction with the other command options.

Options

The following options are supported:

–Z zoneclustername

Specifies the cluster in which the resource is configured. This option is needed only when the command is executed in the global zone but needs to access the Application_user property of a resource in a zone cluster. The –Z option cannot be used within a zone cluster to access a different zone cluster.

If the –Z option is omitted, the resource is assumed to exist in the cluster in which the scha_check_app_user command is executed -- either the global cluster or a zone cluster.

If the scha_check_app_user command is executing in the global zone and the –Z and –R options are both specified, the resource specified with –R resides in the zone cluster specified by –Z, not in the global cluster. In this case, the agent developer should alert the end user to the fact that the username specified by the Application_user property needs to be valid in the global zone even though the resource is configured in a zone cluster.

If the scha_check_app_user command is executing in the global zone and the –Z option is specified, the cmd-path argument identifies a file pathname in the global zone, not in the zone specified by –Z.

–U username

If specified, this username is taken to be the application user name regardless of the executable file owner, the Application_user property setting, or the Resource_security property setting. The –U option can be used when the caller has its own mechanism for determining the application user name and it only wants to check ownership and permission of the executable program. An error results if the real user ID of the caller is non-root and the –U option specifies root.

If the –U option is used together with –Z option, the specified username must be valid in the zone in which the command is executing, not necessarily in the zoneclustername specified by the –Z option.

–R resource

The name of an RGM resource associated with this command execution. If the –U option is not also specified, the application user name is obtained from the Application_user property of this resource. If the resource does not have an Application_user property or that property is not set, the application user name is the owner of the executable file.

If –U is not specified and Resource_security is set to COMPATIBILITY, regardless of the Application_user property setting, the application user name is set to the real user ID of the invoking process. If –U is not specified and the Resource_security property is set to OVERRIDE, regardless of the Application_user property setting, the application user name is set to the owner of the executable file.

If the –R option is specified together with –Z, the resource's Application_user property must specify a username that is valid in the zone in which the command is executing, not necessarily in the zoneclustername specified by the –Z option.

cmd-path

A full pathname to an executable file that the caller proposes to execute as the application user. If the –Z option is specified, the cmd-path is evaluated relative to the zone in which the command is executing, not the zoneclustername specified by the –Z option.

If neither –R nor –U is specified, the application user name is the owner of the executable file, unless Resource_security is set to COMPATIBILITY, in which case the application user name is set to the real user ID of the invoking process.

If the computed application user is root (superuser) but the real user ID of the caller is non-root, the application user name becomes the real user ID of the caller.

Examples

Example 1 Using scha_check_app_user with su in a Script

The following bash script invokes scha_check_app_user prior to using su(8) to execute a command named mycommand that is associated with the RGM resource named myresource:

    COMMANDPATH=/opt/mypkg/bin/mycommand
    RESOURCENAME=myresource
    TMPFILE=$(/usr/bin/mktemp)

    # Here we are redirecting the error/warning messages into 
    # a temp file and will write them later. 
    # Instead, we could just let them flow out to stderr.
    APPUSER=$(/usr/cluster/bin/scha_check_app_user \ 
            -R $RESOURCENAME $COMMANDPATH 2>$TMPFILE)
    errcode=$?

    if [[ $errcode -ne 0 ]]; then
        # Security checks failed -- do not execute the program
        printf "Security checks failed on program %s:\n" $COMMANDPATH
        # Output the error messages
        /usr/bin/cat $TMPFILE
        /usr/bin/rm $TMPFILE
        exit errcode
    fi

    # There may still be warning messages in TMPFILE.
    # Write them for the user.
    /usr/bin/cat $TMPFILE
    /usr/bin/rm $TMPFILE

    # Application user name is in $APPUSER.
    # Execute mycommand with any necessary arguments.
    #
    # Note that the su command might still fail, for example, if
    # this script lacks the necessary privilege to execute as
    # the application user.
    #
    # Other command wrappers such as "su -" or "pfexec" could be used
    # here instead of plain "su".

    su $APPUSER $COMMANDPATH arg1 arg2

Exit Status

The following exit status codes are returned. Error codes are described in scha_calls(3HA).

0 SCHA_ERR_NOERR

The security checks have passed and the command may be executed as the application user. However, when output is written to stderr, it indicates that an error occurred in fetching or checking the application user. Any such warning message should be passed back to the user.

3 SCHA_ERR_INVAL

The command is invoked with invalid arguments. In this case, the application user is not written to stdout. An error message that details one of several possible errors is written to stderr.

6 SCHA_ERR_ACCESS

The file identified by the path argument is not executable; or the –U option specifies root and the real user ID of the caller is non-root; or Resource_security is SECURE and one of the following conditions applies:

  • The executable file is world-writable.

  • The application user is root and the executable file is group-writable.

The SCHA_ERR_ACCESS exit code indicates a security violation, and the caller should not execute the command.

14 SCHA_ERR_RSRC

The rname argument does not identify a valid resource name. In this case, the application user is not written to stdout. An error message is written to stderr.

16 SCHA_ERR_CHECKS

Resource_security is SECURE and the Application_user name does not map to a valid user ID. The SCHA_ERR_CHECKS exit code indicates a security violation, and the caller should not execute the command.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
ha-cluster/developer/api
Interface Stability
Evolving

See Also

Developing Data Services, pfexec(1), scha_calls(3HA), scha_strerror(3HA), attributes(7), cluster(8CL), scha_cmds(8HA), su(8)