Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### 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`(1M) 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`(5) 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`(5).

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 effective 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 effective 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 effective user ID of the invoking process.

If the computed application user is root (superuser) but the effective user ID of the caller is non-root, the application user name becomes the effective 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`(1M) 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 effective user ID of the caller is non-root; or `Resource_security` is `SECURE` and one of the following conditions applies:

  - The executable file is group-writable or world-writable.

  - The application user is root and the executable file is owned by a non-root user.

  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`(5) for descriptions of the following attributes:

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

## See Also

`su`(1M), `pfexec`(1), `cluster`(1CL), `scha_cmds`(1HA), `scha_calls`(3HA), `scha_strerror`(3HA), `attributes`(5), Oracle Solaris Cluster Data Services Developer’s Guide

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |