Appendix: Securing PS_HOME and PS_CFG_HOME

This chapter provides an overview of PS_HOME and PS_CFG_HOME security and discusses how to:

• Secure PS_HOME.

• Secure PS_CFG_HOME.

Understanding PS_HOME and PS_CFG_HOME Security

With the separation of the PS_HOME and PS_CFG_HOME directories, system administrators can implement more secure PeopleSoft deployments by restricting access within each of these directory structures.

This section describes the procedures and considerations involved in configuring these additional security options.

Note. Each site can elect to implement these security measures as needed according to individual security policies.

Note. Each PeopleSoft application you have licensed may have specific instructions regarding the implementation of these security measures. Always check your application-specific documentation for any information you need to consider to ensure both a secure environment and a properly functioning application.

Understanding PS_HOME Security

Because the configuration files, by default, do not reside in PS_HOME, the PS_HOME installation can be locked down to prevent unauthorized access, by user or system process. By making the PS_HOME directory ‘Read-Only’, processes running in the domain cannot write to PS_HOME or any of the subdirectories therein. Likewise, any users with malicious intent are unable to delete or modify executable files in PS_HOME.

Securing PS_HOME involves making the directory read-only, yet making sure that the following system elements have sufficient access.

Note. These instructions do not apply to the PS_HOME residing on the web server for PIA or the PS_HOME on the database server.

Note. When implementing a read-only PS_HOME, consider that environment locations to which processes write files can't be in a read-only location. Settings for "temporary" directories and "output" directories should not be located within the PS_HOME directory structure. For example, the default temporary directory locations are C:\Documents and Settings\<user>.PEOPLESOFT\Local Settings\Temp (Windows) and %root%\TMP (UNIX).

Note. All elements of your PeopleSoft implementation, such as Process Scheduler and SQR can operate within a secure PS_HOME configuration.

Understanding Minimum Access Required by The User Starting Domains

The bare minimum that needs write access at the time a domain boots includes:

• The domain directory: it must be possible to write content to the domain directory although most of the configuration files in this directory can be read-only.

• The domain LOGS directory: by default this is the LOGS directory beneath the domain directory. If this location is overridden in the configuration file, the relevant location must also be read-write.

• The .adm directory: this subdirectory within the domain (if present) must also be read-write. This is required by Oracle Tuxedo.

• The Archive directory: located within the domain directory, a copy of the .cfg is archived to this directory each time it is updated. This directory is also used by the Purge Cache PSADMIN option for application servers.

All other files in the PS_CFG_HOME directory tree can be made read-only to the user starting the domain.

Understanding PS_CFG_HOME Security

Some administrators may want to implement additional security and restrict access to PS_CFG_HOME. For example, in some cases you may want take further steps to limit privileges of the user starting a domain, or lock down configuration files to prevent unintended configuration changes during runtime.

Securing PS_HOME on UNIX

The UNIX operating system lends itself to a read-only configuration for PS_HOME because of the way that Inter-process Communication (IPC) resources are allocated and managed. UNIX was designed to allow multiple users concurrent access to the same physical hardware and file system while enforcing a strong privileges model.

Note. It is necessary to have access to at least two user accounts in order to setup a true and complete read-only environment on UNIX.

To illustrate the procedure, two user accounts are used.

To setup read-only PS_HOME on UNIX:

1. Install PeopleTools using the InstallAdmin account.

2. Verify that PS_HOME is read-only.

   After installing PeopleTools, attempt to delete both a directory and file from PS_HOME using the DomainAdmin account.

   If it is not read-only to the DomainAdmin account, login as the InstallAdmin account and use the chmod command to make PS_HOME read-execute to the world.

   If the DomainAdmin account is a member of the same group as the InstallAdmin account you will need to apply the read-execute restriction to the group also. For example,

   chmod -R 755 $PS_HOME

3. Sign in as the DomainAdmin account, open a shell, and change directory to PS_HOME.

4. Invoke psconfig.sh to set the environment.

5. Create and configure a new domain.

   This can be an application server, search server, or Process Scheduler domain.

6. Start the new domain and verify that all of the domain processes have started.

   For application server domains, ensure that you can sign in through PIA and make successful page requests.

Managing a Secure PS_HOME on UNIX

When deploying a secured PS_HOME environment on UNIX, keep the items in this section in mind.

Working with User Accounts

The user account that boots the domain must be the same user who configures the domain. This is a Tuxedo requirement, not a PeopleTools requirement. This means that the user account under which the domain processes will run must have read-write access to the domain directory.

The owner of the domain processes is the user account who starts the domain. This is different from Microsoft Windows, where the domain processes are booted by the account that starts the Oracle ProcMGR service. If you use both Windows and UNIX servers to deploy PeopleSoft, keep this subtle distinction in mind between the two operating systems.

Configuring Partial PS_HOME Access

In some cases, user accounts may need to access specific parts of the PS_HOME directory tree. This is recommended through the addition of a “hybrid” user to the same group to which the “InstallAdmin” account (the user who installed PeopleTools) belongs. The InstallAdmin can then choose to allow group access to the specific parts of the PS_HOME directory tree to which the hybrid user is permitted read-write access.

For example, consider a scenario where you have installed PeopleTools at your site, but have hired a consultant to help with various implementation tasks. The InstallAdmin only wants to allow the consultant access to specific parts of the PS_HOME directory tree. The account that the consultant uses is therefore a hybrid account. It is has read-write access to PS_HOME, but only to the specific subdirectories deemed necessary.

To achieve this hybrid privilege model, allow group access to those specific directories under PS_HOME to which the consultant requires write access.

Securing PS_HOME on Windows

When securing PS_HOME on Windows, you have these options:

• Multiple administrator user accounts.

• Local user accounts.

Multiple Administrator User Accounts

This method of securing PS_HOME on Windows offers the ability for many administrator user accounts to share the same PS_HOME while managing separate PS_CFG_HOMEs. This method is most appropriate for a production environment.

In this configuration, you install PeopleTools on a server machine, and share the PS_HOME installation location as read-only. Domain administrators may then map to this network drive, and invoke PSADMIN to create and start domains.

Once you have set up a secure PS_HOME, domain creation and the various prerequisites for setup are the same as before. For example, database connectivity must be available on the machine on which the domain will boot. The server where PS_HOME is located acts as a read-only file server for the domains.

To illustrate this procedure, two user accounts are used.

In this scenario, one administrator installs PeopleTools, and a second user, with a more limited set of privileges, creates and administers domains.

The steps for User2 on Machine2 can be applied to multiple users. Any number of users can map to a single read-only PS_HOME.

Note. This information applies to PeopleTools installations on drives assumed to be formatted as NTFS.

To install PS_HOME and restrict privileges:

1. While logged in as User1 on Machine1, run the PeopleTools installation program.

2. Choose Application Server and Batch Server installation options.

   File Server is optional, depending upon whether or not it is required.

3. Ensure that you install PeopleTools such that PS_HOME is not the top most directory on the drive.

   For example,

   D:\PTInstalls\PT8.51.

   Note. This is essential if you plan on accessing PS_HOME as a mapped drive.

4. After the installation has completed, set privileges on the PS_HOME directory tree, using Windows File Sharing.

   • Using Windows Explorer, select the high-level directory (as in D:\PTInstalls), right-click, and select Sharing and Security.

   • On the Properties, Sharing tab, click Share this folder.

   • Click Permissions, and for the Group of Everyone, check the Allow checkbox for Read, make sure the Allow checkbox for Change is not selected, and click Apply and/or OK.

5. Verify that the folder has been shared by making sure the ‘hand’ icon appears on the folder in Windows Explorer.

To set up access to a secure PS_HOME:

1. Sign in as User2 on Machine2.

2. Map a network drive to the shared PS_HOME.

3. Verify that you cannot add, modify, or delete any content below the mapped location.

   This ensures that PS_HOME is read-only. If you can delete or change content in the mapped location, it is possible that User2 is an administrator on Machine1. User2 must not be an administrator on Machine1 for these security measures to be effective.

   If User2 cannot see the shared location there may be a problem with the share or the local network. Make sure the machine can be pinged.

4. Configure Oracle ProcMGR service to allow the User2 account to access PS_HOME.

   This is necessary because by default the Oracle ProcMGR service uses the Local System account.

   1. Select Start, Programs, Administrative Tools, Services, and double-click on the Oracle ProcMGR service.

   2. On the General tab, stop the service, and set the Startup type to Manual.

   3. On the Log On tab, select the This account radio button, and enter the logon information for User2.

   4. Click OK.

      Note. Do not start the service yet.

5. Set the TM_TUXIPC_MAPDRIVER user variable for User2.

   This environment variable must be set to contain any mapped drives required by the domain processes, such as the drive where PS_HOME is located. Use the following format:

   drive1:=\\machine_name1\dirpath1[;drive2:=\\machine_name2\dirpath2[...]]

   For example,

   N:\\10.100.200.300\PTInstalls

   If multiple mapped drives are required, use a semicolon to separate the values, similar to the way directories are expressed in the PATH environment variable.

   Note. Depending on your network, use either the DNS name or the IP address to specify the machine name.

   Note. If the Oracle ProcMGR needs to run unattended, where no user is signed in, set the TM_TUXIPC_MAPDRIVER environment variable as a system environment variable instead of a user environment variable.

6. Start the Oracle ProcMGR service.

   Once started, you can start PSADMIN as you normally would.

Local User Accounts

Using local user account to secure PS_HOME is a machine-bound solution that you may consider during an initial demo, development, or testing environment, where PS_HOME and PS_CFG_HOME reside on the same machine. In this method, only one machine and one domain account is required.

In this scenario, PeopleTools is installed by a user with administrative privileges. In the context of this scenario, this refers to the network domain user, a user that is a member of an existing network domain of users.

Application server domains are administered by a second user with a more limited set of privileges. This second user is created on the local system and only has access to resources on that machine.

In the following procedure, these user types are represented as:

Setting up a secure PS_HOME and restricting privileges:

1. While logged in as User1 on Machine1, install PeopleTools to the server using the install program.

   Choose Application Server and Batch Server installation options. File Server is optional depending upon whether or not it is required.

   Ensure that you install PeopleTools such that PS_HOME is not in the top directory level on the drive. For example, an ideal location would be C:\PTInstalls\PT8.51.

2. While logged in as User1 on Machine1, create the Guest2 user account.

   Create a new user with at least the following attributes:

   • User name

   • Password

   • Select Restricted user on the Group Membership tab.

   • De-select the User must change password at next logon checkbox.

     See Microsoft Windows documentation for more information related to creating users on Microsoft Windows.

3. Verify that the user is a Restricted User by highlighting the user ID and clicking on the Properties tab.

   You may need to exit and re-enter the User Accounts dialog to see the new user added.

4. Make the PS_HOME directory tree read-only.

   1. Open Windows Explorer and navigate to and select the PS_HOME directory location.

   2. Open the Properties dialog and click on the Security tab.

   3. Deny Write access to all Local Users.

To configure access PS_HOME:

1. Setup the Oracle Proc MGR Service to allow the IPC resources to be created using the restricted user ID (Guest2).

   This is necessary because by default the Oracle PRocMGR service uses 'Local System' account which provides greater access to the PS_HOME than desired.

   1. Select Control Panel, Administrative Tools, Services.

   2. Double click on the Oracle ProcMGR and change the Startup Type to Manual.

2. Change the user and password with which the service is started to match the new local user that you created earlier (Guest2).

   Note. Do not start the service, just click OK.

3. Log off and sign on to Machine1 as Guest2.

   In most cases, any error messages that you see when re-signing on can be ignored as they are associated with signing on with restricted permissions.

4. Verify that you cannot delete, update, or add any content to PS_HOME.

5. Before creating a domain your database connectivity must be setup within the restrictions of the guest2 local user account that you have created.

6. Start PSADMIN, and create a new domain, and confirm that the domain boots.

7. Install PIA on a separate machine, and verify that you can signon through PIA.

   Because PIA is not within the scope of the secure PS_HOME, PIA should be installed on an additional machine. This is necessary because PIA needs write access to various locations within PS_HOME.

Managing a Secure PS_HOME on Windows

When deploying a secured PS_HOME environment on UNIX, keep the items in this section in mind. Depending upon your domain configuration and usage pattern, you may need to unlock specific subdirectories of PS_HOME.

Working With Mapped Drives, UNC Paths, and TM_TUXIPC_MAPDRIVER

This page explains mapped drives (Windows share drives) and the use of UNC paths for PeopleTools application server, Process Scheduler server, and search servers. When a PeopleTools domain is started on a Windows machine, it runs under the user for whom the ProcMGR Windows service has been configured. As such, the domain processes inherit the privileges of that user and not the user logged on to the system.

By default, the ProcMGR runs as the Local System account. While the Local System account has most privileges on the local host, it can't usually access UNC paths or mapped drives.

Note. ProcMGR is the Windows service that is responsible for allocating resources to Tuxedo domains.

Accessing UNC Paths and Mapped Drives

To allow PeopleTools domain processes to access UNC paths or mapped drives, it is necessary to start the ProcMGR service using an account that has access to these resources. This is typically a Windows domain account. A domain account refers to an account that logs a user ID on to both a machine and the corporate network. This account has been created by the network administrator. An example of such an account would be BIGCOMPANY\TSawyer.

The ProcMGR should be configured to start as the domain account. On the Log On tab of the service configuration dialog, click This account:, and enter the credentials of the domain account.

UNC Paths

If you plan to use UNC paths to access PS_HOME you must start PSADMIN using a UNC Path. For example:

\\ptinstalls\pt850\APPSERV\psadmin.exe

With the ProcMGR service set to a domain account, you can use PSADMIN to create and configure domains as if PS_HOME were on the local file system.

Mapped Drives

Additional steps are required if you plan on using a mapped drive for your PS_HOME or PS_CFG_HOME. These additional steps are required because Windows services do not recognize mapped drives. However, Oracle Tuxedo provides a mechanism by which the ProcMGR service is permitted to access network drives, which involves defining any mapped drives using an additional environment variable, TM_TUXIPC_MAPDRIVER. If this environment variable has not been set, the domain processes will be unable to recognize the network drives.

To make sure that the TM_TUXIPC_MAPDRIVER variable is visible to the ProcMGR service, it is necessary to set it globally, as a System environment variable. For example, set TM_TUXIPC_MAPDRIVER to:

N:=\\10.233.238.123\PTInstalls

Important! The mapped drive cannot point directly to PS_HOME. The mapping must point to the parent directory above PS_HOME. For example, if PS_HOME is N:\\10.233.238.123\PTInstalls\pt850, TM_TUXIPC_MAPDRIVER should point to N:\\10.233.238.123\PTInstalls. PTInstalls is the parent directory of \pt850, which would resolve to N:\pt850.

Note. When mapping network drives to the PS_HOME is located, make sure to select Reconnect at logon.

Note. The working directory for psadmin.exe, must always be mapped to a letter drive, such as C:, D:, N:, and so on. When starting psadmin.exe, you must do so from the command line (or script) by referencing the full mapped working directory, such as \\ptinstalls\pt851\APPSERV\psadmin.exe. Launching psadmin.exe outside the current working directory (as in, using Start, Run) will cause psadmin.exe to function incorrectly. This restriction is imposed by Tuxedo.

Working With Oracle ProcMGR Windows Service

When logging on with user accounts Oracle ProcMGR service should be set to Manual instead of Automatic. Failure to do so may result in your domain account becoming locked. If set to 'Automatic' the service may continually attempt to start with an expired password causing the network to lock out the domain user account due to successive failed retries.

Note. On Windows servers, it is recommended to have the Windows user logged in running PSADMIN be the same user that runs the ProcMGR service.

See Also

PeopleTools 8.51 Installation for Oracle: "Installing Additional Components," Task 3-1-6: Setting Up the Windows Services for Oracle Tuxedo

Managing TM_TUXIPC_MAPDRIVER

The TM_TUXIPC_MAPDRIVER environment variable needs to be maintained consistent with the mapped drives upon which you access PS_HOME. If the drive mappings change, then you need to make sure the new values are specified in TM_TUXIPC_MAPDRIVER. If the drive mapping represented by the TM_TUXIPC_MAPDRIVER does not exist, the ProcMGR service will fail to start.

Resolving Initialization Timeout Issues

If the PS_HOME used by your domains is on a network drive, you may notice a delay with starting a domain. This is a result of the binaries being loaded from across the network versus from the local disk. This can cause an initialization timeout.

If you notice domain start failures, check for the following message in the Tuxedo log for the domain:

tmboot.16020.15792.-2: CMDTUX_CAT:1859: ERROR: Server process ID 12668
failed to initialize within 60 seconds

In such cases, increase the timeout values in the domain’s psappsrv.env file to accommodate for the slower start time. For example,

TM_BOOTTIMEOUT=300
TM_RESTARTSRVTIMEOUT=300

Note. Changes to the .ENV file are overwritten when the domain is reconfigured.

Implementing PS_CFG_HOME Security

The steps in this section describe techniques for applying more stringent access to a PeopleTools environment by restricting access to PS_CFG_HOME. If you intend to secure PS_CFG_HOME, it is assumed that you have also secured PS_HOME. Securing PS_CFG_HOME enables you to prevent malicious access to content and configuration files located in PS_CFG_HOME and in domain directories.

These steps describe a security implementation where you configure a user account(s) that can create and configure domains, and user account(s) for domain administrators, who can start and stop domains.

It is possible to limit the permissions to PS_CFG_HOME, such that the domain administrator account can:

• Create files and sub-directories in PS_SERVDIR.

  This is necessary for creating log files and temporary files. Tuxedo also requires read-write access to the domain directory.

• Read (but not change or delete) any existing configuration or template files in PS_SERVDIR.

  These files include .cfg, .ubb, .ubx, .val files, and so on.

Note. To apply these permissions, you must do so after the domain has been configured but before it has been started.

Note. Once these permissions have been implemented, only a user account with the appropriate privileges can reconfigure the domain.

Securing PS_CFG_HOME on UNIX

You have these approaches when implementing a secure PS_CFG_HOME on UNIX:

To set up a secure PS_CFG_HOME using sudo:

1. Create and configure the domain.

   For this procedure, assume the user who does this is DomainAdmin.

2. Use sudo to restrict write access to the sensitive configuration files.

   For example, with the sudo command include:

   chmod 555 <filename>

   In this case, only sudo can change the configuration files or restore write access to DomainAdmin.

3. Log in as DomainAdmin, and verify that none of the restricted files can be changed or deleted by the DomainAdmin session.

4. Start the domain as DomainAdmin.

To set up a secure PS_CFG_HOME using two administrator accounts:

1. Create and configure a domain.

   For this procedure, assume the user who does this is DomainAdmin.

2. As the DomainAdmin user, change the permissions on the domain configuration to allow write access to only those files and directories needing to be written to by the user starting the domain.

3. Signon as the DomainBootAdmin user, start PSADMIN, navigate to the Domain Administration menu, and re-configure the domain without making any changes.

   This results in only the TUXCONFIG file being updated.

4. Star the domain as the DomainBootAdmin user.

Securing PS_CFG_HOME on Windows

To secure PS_CFG_HOME on Windows:

1. Ensure that your PS_CFG_HOME is created in a location that is accessible to the user account that needs to start the domain.

   By default, the PS_CFG_HOME location will not be visible to the user account starting the domain because it is created in the user home of the user account creating the domain. Use one of these options to make the PS_CFG_HOME visible to the user account that needs to start the domain:

   • Override the default location for PS_CFG_HOME, by manually setting the PS_CFG_HOME environment variable to a custom value.

   • Enable the restricted user to view the PS_CFG_HOME in the domain creator’s user home. Set the PS_CFG_HOME as a system-level environment variable so that the restricted user will be able to see it when logged on.

2. While signed in as the domain administrator, create and configure your new application server, Process Scheduler, or search server domain.

3. While signed on as the domain administrator, apply the necessary read-write restrictions.

   It is recommended to apply read-only privileges to the entire directory path to the domain.

   1. Using Windows Explorer select the domain directory and open the Properties dialog.

   2. Select the Security tab. If the restricted user is not displayed, click Add to append the user to the list.

   3. Once added, highlight the restricted user ID and ensure that the following actions are checked in the Allow column: Read & Execute, List Folder Contents, Read, and Write.

4. Apply read-only privileges to the sensitive domain files that should be protected from read-write at runtime.

   This typically includes the Tuxedo binary configuration (PSTUXCFG and PSBDMCFG), ASCII configuration files and templates (*.cfg, *.ubb, *.env, *.ubx, *.lst).

   Using Windows Explorer, select each of these files in the domain directory and open the Properties dialog.

   Note. At a minimum, it must be possible for the user starting the domain to write to the .adm and LOGS directory within PS_SERVDIR. Additionally, this user must be permitted to create new files in the domain directory.

5. Sign in as the restricted user, boot the domain, and verify that it is not possible to delete or modify any of the restricted domain files.

   Note. Sign in using the same user account as the one entered in the Oracle ProcMGR service.

   Note. If subsequent configuration changes are required it is necessary to configure the domain while signed in as the administrator account that created and configured the domain.