Valid for Alpha and Integrity server systems only.
Controls the ACME server.
Requires SYSPRV privilege.
Format
SET SERVER ACME_SERVER
1 – Qualifiers
1.1 /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.
1.2 /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.
1.3 /CLUSTER
Issues the SET command to each ACME server in the cluster.
1.4 /CONFIGURE
/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
1.5 /DISABLE
Disables (shuts down) all ACME agents. Additional ACME agents can
be configured.
1.6 /ENABLE
/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.
1.7 /EXIT
Requests a graceful shutdown of the ACME agents. The ACME_SERVER
process will be shut down after pending requests are completed.
1.8 /LOG
/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.
1.9 /NODE
/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.
1.10 /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.
1.11 /RESUME
Resumes normal operation following use of the /SUSPEND qualifier.
1.12 /START
/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 ACME 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 VSI 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.
1.13 /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.
1.14 /TRACE
/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.
1.15 /WAIT
/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.
2 – Examples
1.$ SET SERVER ACME_SERVER/START/LOG
This command starts the ACME server and creates and opens a new
log file.
2.$ 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.
3.$ SET SERVER ACME_SERVER/CONFIGURE=(NAME=VMS,CREDENTIALS=VMS)
This command loads the VMS ACME agent and identifies its
credentials as VMS.