Controls the ACME server.

Requires SYSPRV privilege.

Format

SET SERVER ACME_SERVER

Description

The SET SERVER ACME_SERVER command provides a system manager with the ability to manage the Authentication and Credential Management Extension (ACME) server process, ACME_SERVER. Specifying this command allows you to start, stop, and restart the ACME server.

The ACME_SERVER process is a detached, kernel-threaded server process that services user authentication requests. These requests are received from client processes that use the SYS$ACM system service. One or more ACME agents assist in processing these requests. An ACME agent is a shareable image that is dynamically activated within the ACME_SERVER process.

The ACME_SERVER process is created automatically at system startup with the VMS ACME agent configured and enabled.

By default, the ACME_SERVER process runs under the SYSTEM account profile ([1,4]) with the following privileges: IMPERSONATE, SYSNAM, PSWAPM, SHARE, TMPMBX, EXQUOTA, AUDIT, CMKRNL, WORLD, and SETPRV.

The ACME_SERVER process is created with the following quotas:

ASTLM = 200 BIOLM = 200 BYTLM = 100000 DIOLM = 200 ENQLM = 1000 FILLM = 64 JTQUOTA = 4096 PGFLQUOTA = 200000 (Alpha) PGFLQUOTA = 300000 (I64) PRCLM = 4 TQELM = 64 WSQUOTA = 2048 WSDEFAULT = 1024 WSEXTENT = 4096

Default UIC, privileges, and quotas can be overridden when the server is started.

In the event of an abnormal process termination, the server will automatically restart and run the SYS$MANAGER:ACME$START.COM command procedure. The executive-mode logical name ACMS$START is used to locate this file.

SYS$MANAGER:ACME$START.COM is also run as a result of one of the following commands:

• SET SERVER ACME/START=AUTO command is issued.
• SET SERVER ACME/RESTART command is issued.

The SYS$MANAGER:ACME$START.LOG file contains any information produced during restart in the event of problems.

SYS$MANAGER:ACME$START.COM file can be modified by the user to define which agents are configured during a restart as well as any other server configuration options. It is not replaced during system upgrades. The SYS$MANAGER:ACME$START.TEMPLATE file contains the HP-supplied version of the file.

The ACME_SERVER process directs SYS$ERROR output to the SYS$MANAGER:ACME_SERVER_ERROR.LOG file. This file exists only if unexpected errors are encountered during operation.

Log file entries generated by the server and ACME agents are written by default to the SYS$MANAGER:ACME$SERVER.LOG file.

The SET SERVER ACME commands are used to perform these operations:

• Start and stop the ACME_SERVER process.
• Configure (dynamically load) ACME agents.
• Enable and disable ACME agents (after they are configured).
• Suspend and resume requests processing. (ACME agents reenter "initial" state for system management reasons, for example, system backup operations.)
• Control logging and tracing.

The SHOW SERVER ACME commands are used to display server and agent information.

The following sequence of commands is used to create the server and enable request processing:

1. SET SERVER ACME/START
   This command creates the server process.
2. SET SERVER ACME/CONFIGURE
   This command configures one or more ACME agents.
3. SET SERVER ACME/ENABLE
   This command enables ACME agent request processing.

For additional information, see the SHOW SERVER ACME command and see the Guide to VMS System Security.

For information about the SYS$ACM system service, see the HP OpenVMS System Services Reference Manual.

Qualifiers

/ABORT

Forces the ACME_SERVER process to terminate without graceful shutdown of ACME agents. Pending requests are cancelled.

This command can be used if a malfunctioning ACME agent prevents a graceful shutdown.

/CANCEL

Cancels pending dialogue requests. Pending dialogue requests are outstanding requests to SYS$ACM callers to supply dialogue response data. Active requests being serviced by the ACME_SERVER process are allowed to complete normally.

Can be used only if the /EXIT or /DISABLE qualifier is also specified.

/CLUSTER

Issues the SET command to each ACME server in the cluster.

/CONFIGURE=(NAME=name [,CREDENTIALS=credentials] [,FACILITY=facility] [,FILE=file] [,THREAD_MAX=n][,...])

Dynamically loads an ACME agent. An ACME agent is a shareable image that conforms to the ACME agent plug-in interface specification.

By default, the ACME server looks for an ACME agent file named prefix$name_ACMESHR.EXE, where the prefix is VMS by default and name is the case-insensitive string specified by the NAME keyword. The prefix can be overridden by the FACILITY keyword. Otherwise, a complete file specification can be specified with the FILE keyword.

You must specify the CREDENTIALS keyword if the ACME agent is a domain of interpretation (DOI) agent capable of authenticating users and issuing credentials. The CREDENTIALS keyword specifies the name of the persona extension associated with the ACME agent (see the $PERSONA_EXTENSION_LOOKUP system service). The credentials name must match the name registered by the executive loadable image that implements the persona extension. For credentials other than "VMS", see the documentation provided for the ACME agent and the specific persona extension.

A maximum of eight ACME agents can be configured.

THREAD_MAX Keyword: Usage Considerations

An ACME server worker thread is the authentication request processing thread of execution. The number of worker threads determines the number of authentication requests the ACME server can process simultaneously.

The ACME server assigns a request slot to each in-progress authentication request. The total number of request slots sets a limit on the maximum number of requests the ACME server can have outstanding.

The ACME server limits the number of unprivileged authentication requests it can accept for processing to half the total number of request slots.

If a process makes a call to $ACM and no request slots are available, the process remains in resource wait state until a request slot becomes free.

The number of ACME server worker threads can range from 1 to 32. The default of 4 satisfies most operating environments in which authentication processing time is largely spent waiting for I/O. You may, however, be able to improve throughput by increasing the number of worker threads if, for example, you have a user-written ACME agent that requires more CPU time than most.

You can set the maximum number of ACME server worker threads before you start or restart the server by defining the inner-mode logical name ACME$THREAD_MAXIMUM in the system-wide logical name table. For example:

$ DEFINE/SYSTEM/EXECUTIVE_MODE ACME$THREAD_MAXIMUM 8

You can also use the CONFIGURE qualifier to set the maximum number of server worker threads before you enable the ACME server. For example:

$ SET SERVER ACME /CONFIGURE=THREAD_MAX=6

The CONFIGURE qualifier overrides the value of the ACME$THREAD_MAXIMUM logical, if it is defined.

Because most authentication processing is I/O bound, defining more threads than about one quarter the number of request slots does not gain more throughput.

The ACME server calculates a default number of request slots from the value of MAXPROCESSCNT and the number of available CPUs. You can override the calculated value by defining the inner-mode logical name ACME$REQUEST_MAXIMUM in the system-wide name table before you start or restart the ACME server. For example:

$ DEFINE /SYSTEM /EXECUTIVE_MODE ACME$REQUEST_MAXIMUM 64 $ SET SERVER ACME /RESTART

/DISABLE

Disables (shuts down) all ACME agents. Additional ACME agents can be configured.

/ENABLE[=NAME=(name[,...])]

Enables one or more ACME agents in the specified order. Ordering of ACME agents is significant, as the ACME_SERVER processes user authentication requests in the order specified. The name variable is a case-insensitive string argument.

If you do not specify the NAME keyword, the same list of ACME agents will be enabled that were enabled by a previous /ENABLE command. If no previous /ENABLE command was issued, all configured ACME agents are enabled.

/EXIT

Requests a graceful shutdown of the ACME agents. The ACME_SERVER process will be shut down after pending requests are completed.

/LOG

/NOLOG (default)

Creates and opens a new log file. The log file is named SYS$MANAGER:ACME$SERVER.LOG. It may be redirected by defining the system logical name ACME$SERVER.

/NODE=(node-name[,...])

Issues the SET command to the ACME server on the specified nodes in the order they are entered. The node names must be located within the current cluster.

/RESTART

Requests a graceful shutdown of the ACME agents. The ACME_SERVER process will be shut down after pending requests are completed.

The ACME_SERVER is restarted and the SYS$MANAGER:ACME$START.COM startup procedure runs.

/RESUME

Resumes normal operation following use of the /SUSPEND qualifier.

/START[=AUTO]

/START cannot be used with the /ABORT, /EXIT, or /RESTART qualifiers.

Starts the server process.

The optional keyword, AUTO, causes the server to startup and configure itself using the SYS$MANAGER:ACME$START.COM procedure. By default, the server starts with only the OpenVMS ACMS agent configured. The following options are available:

To change the default privileges:

/PRIVILEGES=(privilege[,...])

To change the default UIC:

/UIC=uic

To change the default quotas:

/AST_LIMIT=n /BUFFER_LIMIT=n /ENQUEUE_LIMIT=n /EXTENT=n /FILE_LIMIT=n /IO_BUFFERED=n /IO_DIRECT=n /JOB_TABLE_QUOTA=n /MAXIMUM_WORKING_SET=n /PAGE_FILE=n /QUEUE_LIMIT=n /SUBPROCESS_LIMIT=n /WORKING_SET=n

You can use the following alternate syntax to specify a list of quotas and their values:

/QUOTAS=(quota=n[,...])

quota is a PQL-style quota name (for example: ASTLM, BIOLM)

See the $CREPRC system service in the HP OpenVMS System Services Reference Manual for a list of PQL-style quota names and descriptions.

To change the image dump setting:

/DUMP (default) /NODUMP

Forces a process dump in the event of an abnormal process termination. The dump is written to SYS$MANAGER: using the image filename and .DMP extension.

/SUSPEND

Suspends operation after all pending requests are completed.

ACME agents are returned to their initial state (open files are closed, for example). This permits system management functions, such as system backups, to be performed without file-open conflicts.

See also the /RESUME qualifier.

/TRACE=n

/NOTRACE

Enables trace mode in the ACME$SERVER log file. Opens the log file if not already opened.

n is a bit-mask with the following assigned bits:

0 agent Enable agent tracing 1 general General (non-specific) tracing 2 vm VM operations 3 ast AST processing 4 wqe WQE parameter values 5 report Agent status/attributes operations 6 message Messaging operations 7 dialogue Dialogue operations 8 resource Agent resource operations 9 callout Agent callout routine 10 callout_status Agent callout return status

If you specify /NOTRACE, trace mode is disabled and the log file remains open.

/WAIT

/NOWAIT (default)

Returns to caller once the server returns a status other than ACME$_BUSY.

Can only be used with /EXIT, /DISABLE, and /SUSPEND qualifiers.

Examples

$ SET SERVER ACME_SERVER/START/LOG
      

This command starts the ACME server and creates and opens a new log file.

$ SET SERVER ACME_SERVER/DISABLE/WAIT/CANCEL
      

This command disables all configured ACME agents, cancelling all requests in progress. Control does not return to the DCL command prompt until the ACME server has completed the cancellations.

$ SET SERVER ACME_SERVER/CONFIGURE=(NAME=VMS,CREDENTIALS=VMS)
      

This command loads the VMS ACME agent and identifies its credentials as VMS.