Configuring the PAM Server

Installation Options › PAM Server Support › Configuring the PAM Server

Configuring the PAM Server

Configuring the PAM Server on a VM system requires setting up the PAM service machine and the setting of some options.

Step 1: Create the PAM Server Service Machine

The PAM Server needs to run in a service machine, normally called PAMSERVE.

Create a VM directory entry for the PAM Server service machine. The PAM Server service machine needs to have at least a 1 cylinder 191 minidisk or equivalent SFS space. We supply a sample directory entry in file PAMSERVE DIRECT on the CAIMAINT 291 minidisk.

USER PAMSERVE PAMDPSWD 24M 48M G               
   IPL CMS PARM AUTOCR       
   IUCV *RPI                                     
   MACHINE ESA                                   
   OPTION ACCT MAXCONN 00032 QUICKDSP            
   CON 0009 3215 T           
   SPOOL 000C 2540 READER A  
   SPOOL 000D 2540 PUNCH A   
   SPOOL 000E 1403 A         
   LINK MAINT    0190 0190 RR
   LINK TCPMAINT 0198 0198 RR
   LINK MAINT    019D 019D RR
   LINK MAINT    019E 019E RR
   LINK TCPMAINT 0591 0591 RR
   LINK TCPMAINT 0592 0592 RR
   MDISK 0191 3390 xxxx 1 vvvvvv MR RPW WPW MPW

Create a standard TCP/IP PROFILE EXEC similar to your other TCP/IP service machines, and place it on the PAMSERVE 191 minidisk. We supply a sample profile in file PAMSERVE PROFILE on the CAIMAINT 291 minidisk:

/* PAM Server service machine PROFILE EXEC */
'Access 198 D'
'Access 591 E'  
'Access 592 F'  
queue “EXEC TCPRUN”

Step 2: Add the CA PAM Server to SYSTEM DTCPARMS

Define the CA PAM Server as a TCP/IP service machine by adding an entry in your SYSTEM DTCPARMS file, normally on the TCPMAINT 198 minidisk. We supply the following sample entry in file PAMSERVE DTCPARMS on the CAIMAINT 291 minidisk:

.* PAM server (PAM) daemon                            
:nick.PAMSERVE  :type.server  :class.pam              
:nick.pam     :type.class                             
              :name.PAM daemon                        
              :command.SRVRPAM                        
              :runtime.C                              
              :diskwarn.YES                           
              :anonymous.NO                           
              :ESM_Enable.Yes                         
              :ESM_Validate.ACFSAFA0                  
              :ESM_Racroute.RPIUCMS                   
              :VMLINK.CAIMAINT 291 (NONAMES

Step 3: Modify the TCPIP Configuration File

Modify your TCPIP Configuration File, normally on the TCPMAINT 198 minidisk, as follows:

Add an entry in the AUTOLOG section for the PAM server:
```
PAMSERVE password    ; PAM Server    
```
Add an entry in the PORT section for the port to be used by the PAM server. For example, to use port 1091:
```
1091 TCP PAMSERVE            ; PAM Server
```

Step 4: Create the PAM Server Configuration File

The PAM Server needs a configuration file named PAMD CONF on the PAMSERVE 191 if a CMS file is used, or pamd.conf if a BFS file is used. This section describes the options that can be specified. You need to create this file with at least the userid statement.

You can define the options in any order. If you specify an option more than once, the last value is taken.
None of the keywords are case sensitive, but the values are. So make sure that you enter things like file names, including the directory portion, in the correct case for the values.
If an option has a default value, it is documented. If the default value is the desired value, you do not need to specify that option in the configuration file.

The following options can be specified in the pamd.conf configuration file:

threads

Specifies the maximum number of threads the PAM Server can start. The default is 32.

userid

Specifies how to handle the mapping of the Linux for zSeries user ID to VM security. Valid values are:

LINUX: Requires that there is a user map record to convert the Linux for zSeries name to a VM security id. If the mapping record does not exist, the logon fails. The default is LINUX.
MVS: Bypasses the user map record and tries to validate the user ID passed directly to the VM security product if the user ID is less than 8 bytes. If the user ID is greater than 7 bytes, the logon fails.
MIXED: Maps the Linux for zSeries user ID to a VM security ID. If the mapping exists, that user ID is used for validation. If the mapping does not exist and the user ID is 8 bytes or less, it will try to perform the validation using the passed in user ID.

port

(optional) Specifies the port number to which clients must send requests to connect to this server. Number must be a positive integer number in the range of 1 to 65535.

Note: There is no default for this option. Therefore, if this configuration file option is not specified, then the -p command line option must be. For example:

port number

requests

(optional) Specifies the maximum number of requests that the server can have pending. Number must be a non-negative integer. If number is zero, then there is no limit to the number of pending requests. If this option is not specified, the maximum number of pending requests is "0". For example:

requests number

linuxdata

Specifies which segment is used to extract UID, GID, Home and Shell values. This operand applies only when the PAM r8 client is being used. If the PAM r12 (or above) client is used, the Linux segment is always used

LINUX: This configures the PAM Server to extract the data from the users Linux segment. This is the default.
OMVS: This configures the PAM Server to extract the data from the users OMVS segment.

LowerCase

(optional) Controls what values the server forces to lower case before returning to the Linux for zSeries system. The allowed values of option are:

username: Server will force the mainframe security id to lower case. Note that a Linux for zSeries name is always returned unchanges. This option applies only to a mainframe security id.
groupname: Server will force the mainframe security group name to lower case.
homedir: Server will force the Linux for zSeries home directory name to lower case.
al: Equivalent to specifying all of the above values.

You may specify multiple values on the command, separated by blanks.

GentleHup

(optional) Controls the response of the server to a hangup signal. The allowed values of option are:

ON: Server will stop listening for new connections. However, the server will continue to accept requests from the connections to current clients. The server will terminate when all clients have closed their connections
OFF: Server will stop listening for new connections. The server will wait for all pending requests to finish and will then close the connections to current clients. The server will then terminate

GentleStop

(optional) Controls the response of the server to an operator STOP command. The allowed values of option are:

ON: Server will stop listening for new connections. However, the server will continue to accept requests from the connections to current clients. The server will terminate when all clients have closed their connections
OFF: Server will stop listening for new connections. The server will wait for all pending requests to finish and will then close the connections to current clients. The server will then terminate

host

Specifies the address of the interface over which the server is to accept connections. This value is optional.

host network-address

Where network‑address specifies a domain name or an IP address in dotted decimal notation. If a domain name is specified, the server will convert it to an IP address.

If this option is specified, the server will only accept connection requests from the interface address specified. If this option is omitted, then the server will accept connection requests from all interface addresses configured for this host.

debug

(optional) Specifies the amount of information that the server should write to the stderr file. The value is set to the bit‑wise OR of all of the arguments on the configuration line. Each number is a decimal integer value. The value is taken as a bit string, with each bit corresponding to a different kind of trace information. Available log levels are listed in the following table. There is no debug level by default.

Value	Debug Information
1	General trace information
2	Trace packets that are read or written to a TCP socket
4	Trace arguments to selected functions
8	Trace connection management
16	Not used
32	Not used
64	Configuration file processing
65535	All tracing

TLSRandomFile

Specifies the file from which the server obtains the initial seed for the pseudo‑random number generator (PNG). The server updates this file each time the server starts so that the starting value of the PNG changes each time the server is run.

TLSCertificateFile

Specifies the path and name of the server's certificate. This certificate must be in PEM format. The server sends this certificate to a client so that the client can validate the server.

This option is required to use TSL or SSL for communications with clients.

Note: If you do not specify a server certificate and the associated private key, no SSL conversation can be started. If SSL_Required is specified on the Linux client, no communications will ever be started.

TLSCertificateKeyFile

Specifies the path and name of a file that contains the secret private key that matches the certificate stored in the TLSCertificateFile file. This file must be in PEM format. If this file is password protected, the server prompts for the password at the time that the server reads the configuration file.

Except as noted below, this option is required to use TLS or SSL for communications with clients.

If the server certificate and the associated private key are stored in the same file, this option can be omitted.

Note: Since you run the server as a disconnected service machine, prompting for a password is not possible. In this case, you should ensure that the private key is not password protected.

TLSCACertificateFile

Specifies the path and name of a file that contains the certificate for all Certificate Authorities that can sign a client certificate. Each certificate must be in PEM format.

If you have a single CA certificate that is used to sign all client certificates, just specify this file with this keyword. If you have more than one CA certificate, concatenate them together into a composite file and specify the path and name of this composite file with this keyword.

TLSVerifyClient

Specifies whether a client is required to present a certificate when attempting to establish a SSL or TLS connection with the server. Valid values are:

NEVER

The server does not request a certificate. This is the default.

Note: The values OFF, NO, or FALSE are accepted and are equivalent to NEVER.

ALLOW

The server requests a certificate. If no certificate is provided, the session proceeds normally. If a bad certificate is provided, it is ignored and the session proceeds normally.

TRY

The server requests a certificate. If no certificate is provided, the session proceeds normally. If a bad certificate is provided, the session terminates immediately.

DEMAND

The server requests a certificate. If no certificate is provided, or a bad certificate is provided, the session terminates immediately.

Note: The values HARD, ON, YES, and TRUE are accepted and are equivalent to DEMAND.

Step 5: Create the SRVRPAM EXEC

Create the SRVRPAM EXEC on the PAM Server 191 minidisk. This exec contains the OPENVM RUN command that starts the PAM server module LXPAMD.

There are two required parameters and one optional parameter used by LXPAMD:

LXPAMD -f config_file -p port [‑d debug_level]'

where:

‑f config_file

Specifies the configuration file to use for startup. This file can be a variable length record CMS file on the 191 minidisk, or it can be a BFS file. The file name can be anything you set up.

The suggested value if you are using a BFS file is:

-f pamd.conf

For a CMS file on the 191 minidisk:

-f “//PAMD CONF”

‑p port

Specifies the startup TCP/IP port that it is running with.

‑d debug_level

Specifies the level of debug and tracing messages to generate. The value can be from 0 to 65535. The default value is 0.

For example, to start PAM using the CMS file PAMD CONF and port 1091, create a SRVRPAM EXEC with the following lines: (We supply this sample in file PAMSERVE SRVRPAM on the CAIMAINT 291 minidisk.)

/* SRVRPAM EXEC - Start the PAM Server */
'OPENVM RUN LXPAMD -f “//PAMD CONF” -p 1091'

If any BFS files are used by the PAM server, an OPENVM MOUNT command for the BFS root is required, as well as an OPENVM SET DIRECTORY command to set the current directory.

For example, to start PAM using port 1091 and the BFS file /usr/lpp/capam/pamd.conf, create a SRVRPAM EXEC with the following lines:

/* SRVRPAM EXEC - Start the PAM Server */
'OPENVM MOUNT /../VMBFS:VMSYS:ROOT/ /'
'OPENVM SET DIRECTORY /usr/lpp/capam'
'OPENVM RUN LXPAMD -f pamd.conf -p 1091'

Step 6: Define the PAM Server ID to Security

Use the following commands to define the PAM Server user ID and started task information in the CA ACF2 for z/VM database:

ACF

SET LID

INSERT PAMSERVE VMESM SECURITY SYNERR(ALLOW) PASSWORD NOPSWD-EXP

SET PROFILE(USER) DIV(OEVM)

INSERT PAMSERVE UID(0)

END

Use the following command to rebuild the OpenExtensions tables:

ACFSERVE RELOAD PROFILE USER