Setting Up Local Security on the Agent

Setting Up Local Security on the Agent
The agent has its own security verification that it performs when it receives instructions from the scheduling manager. Security rules on the agent define the local security verification. Local security on the agent controls which scheduling manager user IDs can perform the following actions:
  • Submit jobs to run under a specific agent user ID.
  • Issue CONTROL messages to the agent.
  • Perform FTP transfers under a specific agent user ID. 
Agent security rules do not override permissions set at the operating system level.
To set up local security on the agent, follow these steps:
When the agent starts, it verifies local security and takes the following actions:
  • If local security is enabled, the agent then looks for the security.txt file.
    • If the security.txt file does not exist, default security rules apply.
    • If the security.txt file exists, the agent uses the rules that are defined in the file. The agent does not use the default security rules. If a request does not have a match in the security file, the agent denies the request.
  • If local security is disabled, the agent does not verify security.
Enable Local Security
For the agent to perform its own security checks, local security must be enabled.
Follow these steps:
  1. Change to the agent installation directory.
  2. Stop the agent.
  3. Open the agentparm.txt file that is located in the agent installation directory.
  4. Define the following parameter:
    security.level=on
  5. Save and close the file.
  6. Start the agent.
    Local security is enabled on the agent.
Configure the security.txt File
The security.txt file contains the rules that allow or deny the scheduling manager user IDs the authority to issue control commands to the agent.
If the security.txt file does not exist, default security rules apply.
Follow these steps:
  1. Change to the agent installation directory.
  2. Stop the agent.
  3. Open the security.txt file, or create one if it does not exist.
    The security.txt file must reside in the agent installation directory.
  4. Save and close the file.
  5. Start the agent.
    Security rules are set for the agent.
Example: Security File Rule
The following line in the security.txt file allows all users to issue all control commands to the agent.
c a * CONTROL *
Security File Rules
The security file contains the following three types of rules:
x a | d
manager_userID
agent_userID
path
Defines a rule that allows or denies the scheduling manager user IDs from submitting jobs that run under a specific user ID, from a specific directory. These rules begin with the letter x.
  • x
    Identifies a rule controlling execution of scripts and commands.
  • a | d
    Specifies whether access is allowed or denied.
    • a
      Indicates that permission is allowed.
    • d
      Indicates that permission is denied.
  • manager
    _
    userID
    Defines the scheduling manager name or the scheduling manager user ID this rule applies to. User IDs are case-sensitive.
  • agent_userID
    Defines the user ID on the agent computer under which the job runs. User IDs are case-sensitive.
  • path
    Defines the path that the scheduling manager is allowed to submit jobs from, using the user ID identified by
    agent_userID
    . Paths are case-sensitive.
HPE Integrity Nonstop:
The previous information is applicable to OSS only.
On AutoSys Workload Automation, jobs are always submitted to run under the user that is specified in the owner attribute. If local security is enabled on the agent, the agent verifies the permissions of the job owner only. The agent does
not
verify the AutoSys Workload Automation user who submits the job. For AutoSys Workload Automation, you can define the security rule as follows:
x a | d
job_owner
agent_userID
path
  • job_owner
    Defines the user that is specified in the owner attribute.
f a | d
FTP_userID
operation
path
Defines a rule that allows or denies FTP user IDs from issuing FTP-related commands to files in specified directories or members of IBM i file objects. These rules begin with the letter f.
  • f
    Identifies FTP commands.
  • a | d
    Specifies whether access is allowed or denied.
    • a
      Indicates that permission is allowed.
    • d
      Indicates that permission is denied.
  • FTP_userID
    Defines the FTP user ID this rule applies to. User IDs are case-sensitive.
  • o
    peration
    Specifies the FTP command. The following commands are valid:
    • list
      Changes directory and list files (CD, LIST, NLST).
    • read
      Retrieves the file (RETR).
    • write
      Stores the file or makes a directory (STOR, STOU, RNFR, RNTO, MKD).
    • delete
      Deletes the file or directory (DELE, RMD).
    These commands apply to the agent as FTP server. For FTP jobs, only read and write commands apply.
  • path
    Specifies the path that the scheduling manager is allowed to submit jobs from, using the user ID identified by
    FTP_userID
    . Paths are case-sensitive.
The previous information is not applicable to Agent for HPE Integrity NonStop.
c a | d
manager_userID
CONTROL
command
Defines a rule that allows or denies scheduling manager user IDs the authority to issue control commands to the agent. These rules begin with the letter c.
  • c
    Identifies a rule controlling operational commands to an agent.
  • a | d
    Specifies whether access is allowed or denied.
    • a
      Indicates that permission is allowed.
    • d
      Indicates that permission is denied.
  • manager_userID
    Defines the scheduling manager name or the scheduling manager user ID this rule applies to. User IDs are case-sensitive.
  • command
    Specifies the control command. The valid commands are shutdown, refresh, flush, quiesce, restart, userverify, and clrfiles. You can also specify an asterisk (*) for all commands.
On AutoSys Workload Automation, you can use this rule to allow or deny the authority to issue the autoping command or to add the scheduling manager instance to the agent. For AutoSys Workload Automation, you can define the security rule as follows:
c a | d
instance
_* * *
  • instance
    Specifies the AutoSys Workload Automation instance.
  • Specify at least one rule of each type (x, f, and c) in the security.txt file.
  • If security.txt does not exist, default security rules apply.
  • Agent security rules do not override permissions set at the operating system level.
  • To specify an f rule that restricts access to a directory itself (not the contents in the directory), the directory path must end with a forward slash.
Examples: Scheduling Manager (x) Security File Rules
The following rule allows any scheduling manager user to submit jobs that use any files from any directory or IBM i object. The user can submit the jobs under any user ID on the agent computer.
x a * * +
The following rule denies any scheduling manager user from submitting jobs under gem, or any user IDs that begin with gem, from all directories.
x d * gem* +
The following rule denies any scheduling manager user from submitting jobs that use any IBM i object or files from any directory under the QSECOFR profile on the agent computer.
x d * QSECOFR +
The following rule allows any scheduling manager user to submit jobs as root that is named employee, or begin with employee, from the /prod/ directory.
x a * root /prod/employee+
The following rule allows any scheduling manager user to submit jobs that use any object in any library on the system. The user can submit the jobs under any user profile that starts with the characters ADMIN on the agent computer.
x a * ADMIN /QSYS.LIB/+
The following rule allows any scheduling manager user to submit jobs that use any object whose name starts with F in the USER library. The user can submit the jobs under any user profile that starts with the characters USR on the agent computer. However, members of file objects whose names start with F are excluded.
x a * USR* /QSYS.LIB/USER.LIB/F*
The following rule allows any scheduling manager user to submit jobs that use any object whose name starts with F in the USER library. The user can submit the jobs under any user profile that starts with the characters JO on the agent computer. Members of file objects whose names start with F are included.
x a * JO* /QSYS.LIB/USER.LIB/F*
The following rule denies any scheduling manager user from submitting jobs that use /QSYS.LIB/MLIB.LIB/DEPT.FILE/ PAYROLL.MBR on the agent computer.
x d * * /QSYS.LIB/MLIB.LIB/DEPT.FILE/PAYROLL.MBR
Examples: FTP (f) Security File Rules
The following rule denies all users from using any FTP operations in any directory. To allow specific FTP access, the FTP rules that follow override this general rule.
f d * * +
The following rule allows all users to list the files in /pub/ftp and its subdirectories:
f a * list /pub/ftp/+
The following rule allows all users to store files, rename files, and make directories in /pub/ftp/upload and its subdirectories:
f a * write /pub/ftp/upload/+
The following rule allows all users to read files from /pub/ftp/download and its subdirectories:
f a * read /pub/ftp/download/+
Examples: Command (c) Security File Rules
The following rule allows all users to issue control commands to the agent:
c a * * *
The following rule allows the autoping command to be issued to the agent from the ACE instance:
c a ACE_* * *
Format for Defining an IBM i Object in an Execution Rule
To define an IBM i object in an execution rule, use the path file format only. No other naming convention is supported in the security rules. The path naming format has the form:
/QSYS.LIB/
libraryname
.LIB/
objectname
.
type
  • libraryname
    Defines the name of the library that contains the object. The value can be as follows:
    • A specific library name
    • %LIBL% -- Lets the agent validate the permission against a library list that the IBM i system resolves when the library is not specified in the CLPNAME, COMMAND, AS400FILE, or AS400LIB statements.
    Limits:
    Up to 10 characters
  • objectname
    Defines the object name.
    Limits:
    Up to 10 characters
  • type
    Defines the object type.
    Limits:
    CMD, PGM, or FILE
For *FILE objects, you can specify the member name as follows:
/QSYS.LIB/
libraryname
.LIB/
objectname
.FILE/
membername
.MBR
  • membername
    Defines the member name for the file object.
    Limits
    : Up to 10 characters
Additional Formats for Security File Rules
When defining security rules in the security.txt file, you can also use the following formats:
  • Wildcards
    The scheduling manager name, user IDs, object names, paths, verbs, and subverbs can contain a single wildcard character at the end of the value only.
    The following wildcards are valid:
    • Asterisk (*) -- Represents zero or more characters matches in the current directory only.
    • Plus sign (+) -- Represents zero or more characters matches in the current directory and all subdirectories. For a FILE object, + applies to the members within it.
  • Start point and spacing
    Every security rule starts in column 1. Separate items on a line by one or more blanks or tab characters, and end with a new-line character.
  • Comment lines
    The file can contain comment lines. An asterisk (*) or a number sign (#) in column 1 identifies comment lines.
Security Rule Interpretation
For a rule to match, three components of a rule have to match. If two or more rules match, the closest match overrides the others, as follows.
Interpretation
Explanation
A specific rule overrides a generic rule. A generic rule is a rule that contains wildcards.
/u1/jsmith overrides /u1/jsmith*
CYBDL01 overrides *CYB
If both rules are generic, the more specific one overrides the other.
/u1/jsmith/scripts/* overrides /u1/jsmith*
/u1/jsmith/scripts/a* overrides /u1/jsmith/scripts*
If there is still ambiguity after these rules have been applied, a deny rule overrides an allow rule.
c d USR* * *overrides c a USR* * *
Default Security Rules
When the agent starts, it looks to see whether local security is turned on. If local security is turned on (security.level is set to on in the agentparm.txt file), the agent then looks for the security file.
After installation, the security.txt file contains the following security rules:
c a * * * f d * * + x d * * +
Agent for HPE Integrity Nonstop:
The second and third lines in the security.txt file are ignored.
The following default security rules apply when the security file does not exist and agent security is turned on in the agentparm.txt file (security.level=on):
x a * * + x d * root + c a * * * f a * * +
For WA Agent for Windows, substitute administrator for root.
Refresh an Agent Security File
For any changes to take effect, refresh the agent security file.
To refresh an agent security file, enter the following command from the command prompt:
cybAgent -r