1saf(1M) System Administration Commands saf(1M)
2
6 saf - Service Access Facility
7
9 The SAF generalizes the procedures for service access so that login
10 access on the local system and network access to local services are
11 managed in similar ways. Under the SAF, systems may access services
12 using a variety of port monitors, including ttymon, the listener, and
13 port monitors written expressly for a user's application. The manner in
14 which a port monitor observes and manages access ports is specific to
15 the port monitor and not to any component of the SAF. Users may there‐
16 fore extend their systems by developing and installing their own port
17 monitors. One of the important features of the SAF is that it can be
18 extended in this way by users.
19 Relative to the SAF, a service is a process that is started. There are
22 no restrictions on the functions a service may provide. The SAF con‐
23 sists of a controlling process, the service access controller (SAC),
24 and two administrative levels corresponding to two levels in the sup‐
25 porting directory structure. The top administrative level is concerned
26 with port monitor administration, the lower level with service adminis‐
27 tration. The SAC is documented in the sac(1M) man page. The administra‐
28 tive levels and associated utilities are documented in the System
29 Administration Guide - Volume II. The requirements for writing port
30 monitors and the functions a port monitor must perform to run under the
31 SAF and the SAC are documented here.
32 Port Monitors
34 A port monitor is a process that is responsible for monitoring a set of
35 homogeneous, incoming ports on a machine. A port monitor's major pur‐
36 pose is to detect incoming service requests and to dispatch them appro‐
37 priately.
38 A port is an externally seen access point on a system. A port may be an
41 address on a network (TSAP or PSAP), a hardwired terminal line, an
42 incoming phone line, etc. The definition of what constitutes a port is
43 strictly a function of the port monitor itself.
44 A port monitor performs certain basic functions. Some of these are
47 required to conform to the SAF; others may be specified by the require‐
48 ments and design of the port monitor itself. Port monitors have two
49 main functions: managing ports and monitoring ports for indications of
50 activity.
51 Port Management The first function of a port monitor is to man‐
53 age a port. The actual details of how a port is
54 managed are defined by the person who defines
55 the port monitor. A port monitor is not
56 restricted to handling a single port; it may
57 handle multiple ports simultaneously.
58 Some examples of port management are setting the
60 line speed on incoming phone connections, bind‐
61 ing an appropriate network address, reinitializ‐
62 ing the port when the service terminates, out‐
63 putting a prompt, etc.
64 Activity Monitoring The second function of a port monitor is to mon‐
67 itor the port or ports for which it is responsi‐
68 ble for indications of activity. Two types of
69 activity may be detected.
70 The first is an indication to the port monitor
72 to take some port monitor-specific action.
73 Pressing the break key to indicate that the line
74 speed should be cycled is an example of a port
75 monitor activity. Not all port monitors need to
76 recognize and respond to the same indications.
77 The indication used to attract the attention of
78 the port monitor is defined by the person who
79 defines the port monitor.
80 The second is an incoming service request. When
82 a service request is received, a port monitor
83 must be able to determine which service is being
84 requested from the port on which the request is
85 received. The same service may be available on
86 more than one port.
87 Other Port Monitor Functions
90 This section briefly describes other port monitor functions.
91 Restricting Access to the System
93 A port monitor must be able to restrict access to the system with‐
95 out disturbing services that are still running. In order to do
96 this, a port monitor must maintain two internal states: enabled and
97 disabled. The port monitor starts in the state indicated by the
98 ISTATE environment variable provided by the sac. See sac(1M) for
99 details. Enabling or disabling a port monitor affects all ports for
100 which the port monitor is responsible. If a port monitor is respon‐
101 sible for a single port, only that port will be affected. If a port
102 monitor is responsible for multiple ports, the entire collection of
103 ports will be affected. Enabling or disabling a port monitor is a
104 dynamic operation: it causes the port monitor to change its inter‐
105 nal state. The effect does not persist across new invocations of
106 the port monitor. Enabling or disabling an individual port, how‐
107 ever, is a static operation: it causes a change to an administra‐
108 tive file. The effect of this change will persist across new invo‐
109 cations of the port monitor.
110 Creating utmpx Entries
113 Port monitors are responsible for creating utmpx entries with the
115 type field set to USER_PROCESS for services they start. If this
116 action has been specified, by using the -fu option in the pmadm
117 command line that added the service, these utmpx entries may in
118 turn be modified by the service. When the service terminates, the
119 utmpx entry must be set to DEAD_PROCESS.
120 Port Monitor Process IDs and Lock Files
123 When a port monitor starts, it writes its process id into a file
125 named _pid in the current directory and places an advisory lock on
126 the file.
127 Changing the Service Environment: Running
130 doconfig(3NSL) Before invoking the service designated in the port
132 monitor administrative file, _pmtab, a port monitor must arrange
133 for the per-service configuration script to be run, if one exists,
134 by calling the library function doconfig(3NSL). Because the per-
135 service configuration script may specify the execution of
136 restricted commands, as well as for other security reasons, port
137 monitors are invoked with root permissions. The details of how ser‐
138 vices are invoked are specified by the person who defines the port
139 monitor.
140 Terminating a Port Monitor
143 A port monitor must terminate itself gracefully on receipt of the
145 signal SIGTERM. The termination sequence is the following:
146 1. The port monitor enters the stopping state; no further
148 service requests are accepted.
149 2. Any attempt to re-enable the port monitor will be
151 ignored.
152 3. The port monitor yields control of all ports for which
154 it is responsible. It must be possible for a new instan‐
155 tiation of the port monitor to start correctly while a
156 previous instantiation is stopping.
157 4. The advisory lock on the process id file is released.
159 Once this lock is released, the contents of the process
160 id file are undefined and a new invocation of the port
161 monitor may be started.
162 SAF Files
165 This section briefly covers the files used by the SAF.
166 The Port Monitor Administrative File
168 A port monitor's current directory contains an administrative file
170 named _pmtab; _pmtab is maintained by the pmadm command in conjunc‐
171 tion with a port monitor-specific administrative command.
172 The port monitor administrative command for a listen port monitor
174 is nlsadmin(1M); the port monitor administrative command for ttymon
175 is ttyadm(1M). Any port monitor written by a user must be provided
176 with an administrative command specific to that port monitor to
177 perform similar functions.
178 Per-Service Configuration Files
181 A port monitor's current directory also contains the per-service
183 configuration scripts, if they exist. The names of the per-service
184 configuration scripts correspond to the service tags in the _pmtab
185 file.
186 Private Port Monitor Files
189 A port monitor may create private files in the directory
191 /var/saf/tag, where tag is the name of the port monitor. Examples
192 of private files are log files or temporary files.
193 The SAC/Port Monitor Interface
196 The SAC creates two environment variables for each port monitor it
197 starts:PMTAG and ISTATE.
198 This variable is set to a unique port monitor tag by the SAC. The port
201 monitor uses this tag to identify itself in response to sac messages.
202 ISTATE is used to indicate to the port monitor what its initial inter‐
203 nal state should be. ISTATE is set to "enabled" or "disabled" to indi‐
204 cate that the port monitor is to start in the enabled or disabled state
205 respectively.
206 The SAC performs a periodic sanity poll of the port monitors. The SAC
209 communicates with port monitors through FIFOs. A port monitor should
210 open _pmpipe, in the current directory, to receive messages from the
211 SAC and ../_sacpipe to send return messages to the SAC.
212 Message Formats
214 This section describes the messages that may be sent from the SAC to a
215 port monitor (sac messages), and from a port monitor to the SAC (port
216 monitor messages). These messages are sent through FIFOs and are in the
217 form of C structures.
218 sac Messages The format of messages from the SAC is defined by the
220 structure sacmsg:
221 struct sacmsg
223 {
224 int sc_size; /* size of optional data portion */
225 char sc_type; /* type of message */
226 };
227 The SAC may send four types of messages to port monitors. The type of
233 message is indicated by setting the sc_type field of the sacmsg struc‐
234 ture to one of the following:
235 SC_STATUS status request
237 SC_ENABLE enable message
240 SC_DISABLE disable message
243 SC_READDB message indicating that the port monitor's _pmtab file
246 should be read
247 The sc_size field indicates the size of the optional data part of the
251 message. See "Message Classes." For Solaris, sc_size should always be
252 set to 0. A port monitor must respond to every message sent by the sac.
253 Port Monitor Messages
255 The format of messages from a port monitor to the SAC is defined by the
256 structure pmmsg:
257 struct pmmsg {
259 char pm_type; /* type of message */
260 unchar_t pm_state; /* current state of port monitor */
261 char pm_maxclass; /* maximum message class this port
262 monitor understands */
263 char pm_tag[PMTAGSIZE + 1]; /* port monitor's tag */
264 int pm_size; /* size of optional data portion */
265 };
266 Port monitors may send two types of messages to the SAC. The type of
270 message is indicated by setting the pm_type field of the pmmsg struc‐
271 ture to one of the following:
272 PM_STATUS state information
274 PM_UNKNOWN negative acknowledgment
277 For both types of messages, the pm_tag field is set to the port moni‐
281 tor's tag and the pm_state field is set to the port monitor's current
282 state. Valid states are:
283 PM_STARTING starting
285 PM_ENABLED enabled
288 PM_DISABLED disabled
291 PM_STOPPING stopping
294 The current state reflects any changes caused by the last message from
298 the SAC. The status message is the normal return message. The negative
299 acknowledgment should be sent only when the message received is not
300 understood. pm_size indicates the size of the optional data part of the
301 message. pm_maxclass is used to specify a message class. Both are dis‐
302 cussed under "Message Classes." In Solaris, always set pm_maxclass to 1
303 and sc_size to 0. Port monitors may never initiate messages; they may
304 only respond to messages that they receive.
305 Message Classes
307 The concept of message class has been included to accommodate possible
308 SAF extensions. The messages described above are all class 1 messages.
309 None of these messages contains a variable data portion; all pertinent
310 information is contained in the message header. If new messages are
311 added to the protocol, they will be defined as new message classes (for
312 example, class 2). The first message the SAC sends to a port monitor
313 will always be a class 1 message. Since all port monitors, by defini‐
314 tion, understand class 1 messages, the first message the SAC sends is
315 guaranteed to be understood. In its response to the SAC, the port moni‐
316 tor sets the pm_maxclass field to the maximum message class number for
317 that port monitor. The SAC will not send messages to a port monitor
318 from a class with a larger number than the value of pm_maxclass.
319 Requests that require messages of a higher class than the port monitor
320 can understand will fail. For Solaris, always set pm_maxclass to 1.
321 For any given port monitor, messages of class pm_maxclass and messages
324 of all classes with values lower than pm_maxclass are valid. Thus, if
325 the pm_maxclass field is set to 3, the port monitor understands mes‐
326 sages of classes 1, 2, and 3. Port monitors may not generate messages;
327 they may only respond to messages. A port monitor's response must be of
328 the same class as the originating message. Since only the SAC can gen‐
329 erate messages, this protocol will function even if the port monitor is
330 capable of dealing with messages of a higher class than the SAC can
331 generate. pm_size (an element of the pmmsg structure) and sc_size (an
332 element of the sacmsg structure) indicate the size of the optional data
333 part of the message. The format of this part of the message is unde‐
334 fined. Its definition is inherent in the type of message. For Solaris,
335 always set both sc_size and pm_size to 0.
336 Administrative Interface
338 This section discusses the port monitor administrative files available
339 under the SAC.
340 The SAC Administrative File _sactab
342 The service access controller's administrative file contains informa‐
343 tion about all the port monitors for which the SAC is responsible. This
344 file exists on the delivered system. Initially, it is empty except for
345 a single comment line that contains the version number of the SAC. Port
346 monitors are added to the system by making entries in the SAC's admin‐
347 istrative file. These entries should be made using the administrative
348 command sacadm(1M) with a -a option. sacadm(1M) is also used to remove
349 entries from the SAC's administrative file. Each entry in the SAC's
350 administrative file contains the following information.
351 PMTAG A unique tag that identifies a particular port monitor. The
353 system administrator is responsible for naming a port moni‐
354 tor. This tag is then used by the SAC to identify the port
355 monitor for all administrative purposes. PMTAG may consist
356 of up to 14 alphanumeric characters.
357 PMTYPE The type of the port monitor. In addition to its unique tag,
360 each port monitor has a type designator. The type designator
361 identifies a group of port monitors that are different invo‐
362 cations of the same entity. ttymon and listen are examples
363 of valid port monitor types. The type designator is used to
364 facilitate the administration of groups of related port mon‐
365 itors. Without a type designator, the system administrator
366 has no way of knowing which port monitor tags correspond to
367 port monitors of the same type. PMTYPE may consist of up to
368 14 alphanumeric characters.
369 FLGS The flags that are currently defined are:
372 d When started, do not enable the port monitor.
374 x Do not start the port monitor.
377 If no flag is specified, the default action is taken. By
379 default a port monitor is started and enabled.
380 RCNT The number of times a port monitor may fail before being
383 placed in a failed state. Once a port monitor enters the
384 failed state, the SAC will not try to restart it. If a count
385 is not specified when the entry is created, this field is
386 set to 0. A restart count of 0 indicates that the port moni‐
387 tor is not to be restarted when it fails.
388 COMMAND A string representing the command that will start the port
391 monitor. The first component of the string, the command
392 itself, must be a full path name.
393 The Port Monitor Administrative File _pmtab
396 Each port monitor will have two directories for its exclusive use. The
397 current directory will contain files defined by the SAF (_pmtab, _pid)
398 and the per-service configuration scripts, if they exist. The directory
399 /var/saf/pmtag, where pmtag is the tag of the port monitor, is avail‐
400 able for the port monitor's private files. Each port monitor has its
401 own administrative file. The pmadm(1M) command should be used to add,
402 remove, or modify service entries in this file. Each time a change is
403 made using pmadm(1M), the corresponding port monitor rereads its admin‐
404 istrative file. Each entry in a port monitor's administrative file
405 defines how the port monitor treats a specific port and what service is
406 to be invoked on that port. Some fields must be present for all types
407 of port monitors. Each entry must include a service tag to identify the
408 service uniquely and an identity to be assigned to the service when it
409 is started (for example, root).
410 The combination of a service tag and a port monitor tag uniquely define
413 an instance of a service. The same service tag may be used to identify
414 a service under a different port monitor. The record must also contain
415 port monitor specific data (for example, for a ttymon port monitor,
416 this will include the prompt string which is meaningful to ttymon).
417 Each type of port monitor must provide a command that takes the neces‐
418 sary port monitor-specific data as arguments and outputs these data in
419 a form suitable for storage in the file. The ttyadm(1M) command does
420 this for ttymon and nlsadmin(1M) does it for listen. For a user-defined
421 port monitor, a similar administrative command must also be supplied.
422 Each service entry in the port monitor administrative file must have
423 the following format and contain the information listed below:
424 svctag:flgs:id:reserved:reserved:reserved:pmspecific# comment
426 SVCTAG is a unique tag that identifies a service. This tag is unique
431 only for the port monitor through which the service is available. Other
432 port monitors may offer the same or other services with the same tag. A
433 service requires both a port monitor tag and a service tag to identify
434 it uniquely. SVCTAG may consist of up to 14 alphanumeric characters.
435 The service entries are defined as:
436 FLGS Flags with the following meanings may currently be
438 included in this field:
439 x Do not enable this port. By default the port is
441 enabled.
442 u Create a utmpx entry for this service. By default
445 no utmpx entry is created for the service.
446 ID The identity under which the service is to be started.
450 The identity has the form of a login name as it appears
451 in /etc/passwd.
452 PMSPECIFIC Examples of port monitor information are addresses, the
455 name of a process to execute, or the name of a STREAMS-
456 based pipe to pass a connection through. This information
457 will vary to meet the needs of each different type of
458 port monitor.
459 COMMENT A comment associated with the service entry. Port moni‐
462 tors may ignore the u flag if creating a utmpx entry for
463 the service is not appropriate to the manner in which the
464 service is to be invoked. Some services may not start
465 properly unless utmpx entries have been created for them
466 (for example, login). Each port monitor administrative
467 file must contain one special comment of the form:
468 # VERSION=value
470 where value is an integer that represents the port moni‐
472 tor's version number. The version number defines the for‐
473 mat of the port monitor administrative file. This comment
474 line is created automatically when a port monitor is
475 added to the system. It appears on a line by itself,
476 before the service entries.
477 Monitor-Specific Administrative Command
480 Previously, two pieces of information included in the _pmtab file were
481 described: the port monitor's version number and the port monitor part
482 of the service entries in the port monitor's _pmtab file. When a new
483 port monitor is added, the version number must be known so that the
484 _pmtab file can be correctly initialized. When a new service is added,
485 the port monitor part of the _pmtab entry must be formatted correctly.
486 Each port monitor must have an administrative command to perform these
487 two tasks. The person who defines the port monitor must also define
488 such an administrative command and its input options. When the command
489 is invoked with these options, the information required for the port
490 monitor part of the service entry must be correctly formatted for
491 inclusion in the port monitor's _pmtab file and must be written to the
492 standard output. To request the version number the command must be
493 invoked with a -V option; when it is invoked in this way, the port mon‐
494 itor's current version number must be written to the standard output.
495 If the command fails for any reason during the execution of either of
496 these tasks, no data should be written to standard output.
497 The Port Monitor/Service Interface
499 The interface between a port monitor and a service is determined solely
500 by the service. Two mechanisms for invoking a service are presented
501 here as examples.
502 New Service Invocations
504 The first interface is for services that are started anew with each
506 request. This interface requires the port monitor to first fork(2)
507 a child process. The child will eventually become the designated
508 service by performing an exec(1). Before the exec(1) happens, the
509 port monitor may take some port monitor-specific action; however,
510 one action that must occur is the interpretation of the per-service
511 configuration script, if one is present. This is done by calling
512 the library routine doconfig(3NSL).
513 Standing Service Invocations
516 The second interface is for invocations of services that are
518 actively running. To use this interface, a service must have one
519 end of a stream pipe open and be prepared to receive connections
520 through it.
521 Port Monitor Requirements
524 To implement a port monitor, several generic requirements must be met.
525 This section summarizes these requirements. In addition to the port
526 monitor itself, an administrative command must be supplied.
527 Initial Environment When a port monitor is started, it expects an
529 initial execution environment in which:
530 o It has no file descriptors open
532 o It cannot be a process group leader
534 o It has an entry in /etc/utmpx of type
536 LOGIN_PROCESS
537 o An environment variable, ISTATE, is
539 set to "enabled" or "disabled" to
540 indicate the port monitor's correct
541 initial state
542 o An environment variable, PMTAG, is
544 set to the port monitor's assigned
545 tag
546 o The directory that contains the port
548 monitor's administrative files is its
549 current directory
550 o pThe port monitor is able to create
552 private files in the directory
553 /var/saf/tag, where tag is the port
554 monitor's tag
555 o The port monitor is running with user
557 id 0 (root)
558 Important Files Relative to its current directory, the following
561 key files exist for a port monitor.
562 _config The port monitor's configura‐
564 tion script. The port monitor
565 configuration script is run by
566 the SAC. The SAC is started by
567 init(1M) as a result of an
568 entry in /etc/inittab that
569 calls sac(1M).
570 _pid The file into which the port
573 monitor writes its process id.
574 _pmtab The port monitor's administra‐
577 tive file. This file contains
578 information about the ports and
579 services for which the port
580 monitor is responsible.
581 _pmpipe The FIFO through which the port
584 monitor will receive messages
585 from the SAC.
586 svctag The per-service configuration
589 script for the service with the
590 tag svctag.
591 ../_sacpipe The FIFO through which the port
594 monitor will send messages to
595 sac(1M).
596 Port Monitor Responsibilities
600 A port monitor is responsible for performing the following tasks in
601 addition to its port monitor function:
602 o Write its process id into the file _pid and place an advi‐
604 sory lock on the file
605 o Terminate gracefully on receipt of the signal SIGTERM
607 o Follow the protocol for message exchange with the SAC
609 A port monitor must perform the following tasks during service invoca‐
612 tion:
613 o Create a utmpx entry if the requested service has the u flag
615 set in _pmtab
616 o Port monitors may ignore this flag if creating a utmpx entry
618 for the service does not make sense because of the manner in
619 which the service is to be invoked. On the other hand, some
620 services may not start properly unless utmpx entries have
621 been created for them.
622 o Interpret the per-service configuration script for the
624 requested service, if it exists, by calling the docon‐
625 fig(3NSL) library routine
626 Configuration Files and Scripts
628 The library routine doconfig(3NSL), defined in libnsl.so, interprets
629 the configuration scripts contained in the files /etc/saf/_sysconfig
630 (the per-system configuration file), and /etc/saf/pmtag/_config (per-
631 port monitor configuration files); and in /etc/saf/pmtag/svctag (per-
632 service configuration files). Its syntax is:
633 #include <sac.h>
635 int doconfig (int fd, char *script, long rflag);
636 script is the name of the configuration script; fd is a file descriptor
641 that designates the stream to which stream manipulation operations are
642 to be applied; rflag is a bitmask that indicates the mode in which
643 script is to be interpreted. rflag may take two values, NORUN and NOAS‐
644 SIGN, which may be or'd. If rflag is zero, all commands in the configu‐
645 ration script are eligible to be interpreted. If rflag has the NOASSIGN
646 bit set, the assign command is considered illegal and will generate an
647 error return. If rflag has the NORUN bit set, the run and runwait com‐
648 mands are considered illegal and will generate error returns. If a com‐
649 mand in the script fails, the interpretation of the script ceases at
650 that point and a positive integer is returned; this number indicates
651 which line in the script failed. If a system error occurs, a value of
652 −1 is returned. If a script fails, the process whose environment was
653 being established should not be started. In the example, doconfig(3NSL)
654 is used to interpret a per-service configuration script.
655 ...
657 if ((i = doconfig (fd, svctag, 0)) != 0){
658 error ("doconfig failed on line %d of script %s",i,svctag);
659 }
660 The Per-System Configuration File
664 The per-system configuration file, /etc/saf/_sysconfig, is deliv‐
666 ered empty. It may be used to customize the environment for all
667 services on the system by writing a command script in the inter‐
668 preted language described in this chapter and on the doconfig(3NSL)
669 manpage. When the SAC is started, it calls the doconfig(3NSL) func‐
670 tion to interpret the per-system configuration script. The SAC is
671 started when the system enters multiuser mode.
672 Per-Port Monitor Configuration Files
675 Per-port monitor configuration scripts (/etc/saf/pmtag/_config) are
677 optional. They allow the user to customize the environment for any
678 given port monitor and for the services that are available through
679 the ports for which that port monitor is responsible. Per-port mon‐
680 itor configuration scripts are written in the same language used
681 for per-system configuration scripts. The per-port monitor configu‐
682 ration script is interpreted when the port monitor is started. The
683 port monitor is started by the SAC after the SAC has itself been
684 started and after it has run its own configuration script,
685 /etc/saf/_sysconfig. The per-port monitor configuration script may
686 override defaults provided by the per-system configuration script.
687 Per-Service Configuration Files
690 Per-service configuration files allow the user to customize the
692 environment for a specific service. For example, a service may
693 require special privileges that are not available to the general
694 user. Using the language described in the doconfig(3NSL) manpage,
695 you can write a script that will grant or limit such special privi‐
696 leges to a particular service offered through a particular port
697 monitor. The per-service configuration may override defaults pro‐
698 vided by higher-level configuration scripts. For example, the per-
699 service configuration script may specify a set of STREAMS modules
700 other than the default set.
701 The Configuration Language
704 The language in which configuration scripts are written consists of a
705 sequence of commands, each of which is interpreted separately. The fol‐
706 lowing reserved keywords are defined: assign, push, pop, runwait, and
707 run. The comment character is #. Blank lines are not significant. No
708 line in a command script may exceed 1024 characters.
709 assign variable=value
711 Used to define environment variables; variable is the name of the
713 environment variable and value is the value to be assigned to it.
714 The value assigned must be a string constant; no form of parameter
715 substitution is available. value may be quoted. The quoting rules
716 are those used by the shell for defining environment variables.
717 assign will fail if space cannot be allocated for the new variable
718 or if any part of the specification is invalid.
719 push module1[,module2, module3, . . .]
722 Used to push STREAMS modules onto the stream designated by fd; mod‐
724 ule1 is the name of the first module to be pushed, module2 is the
725 name of the second module to be pushed, and so on. The command will
726 fail if any of the named modules cannot be pushed. If a module can‐
727 not be pushed, the subsequent modules on the same command line will
728 be ignored and modules that have already been pushed will be
729 popped.
730 pop [module]
733 Used to pop STREAMS modules off the designated stream. If pop is
735 invoked with no arguments, the top module on the stream is popped.
736 If an argument is given, modules will be popped one at a time until
737 the named module is at the top of the stream. If the named module
738 is not on the designated stream, the stream is left as it was and
739 the command fails. If module is the special keyword ALL, then all
740 modules on the stream will be popped. Only modules above the top‐
741 most driver are affected.
742 runwait command
745 The runwait command runs a command and waits for it to complete;
747 command is the path name of the command to be run. The command is
748 run with /bin/sh -c prepended to it; shell scripts may thus be exe‐
749 cuted from configuration scripts. The runwait command will fail if
750 command cannot be found or cannot be executed, or if command exits
751 with a nonzero status.
752 run command
755 The run command is identical to runwait except that it does not
757 wait for command to complete; command is the path name of the com‐
758 mand to be run. run will not fail unless it is unable to create
759 achild process to execute the command. Although they are syntacti‐
760 cally indistinguishable, some of the commands available to run and
761 runwait are interpreter built-in commands. Interpreter built-ins
762 are used when it is necessary to alter the state of a process
763 within the context of that process. The doconfig interpreter built-
764 in commands are similar to the shell special commands and, like
765 these, they do not spawn another process for execution. See the
766 sh(1) man page. The initial set of built-in commands is: cd,
767 ulimit, umask.
768 Sample Port Monitor Code
771 This example shows an example of a "null" port monitor that simply
772 responds to messages from the SAC.
773 ># include <stdlib.h>
775 # include <stdio.h>
776 # include <unistd.h>
777 # include <fcntl.h>
778 # include <signal.h>
779 # include <sac.h>
780 char Scratch[BUFSIZ]; /* scratch buffer */
782 char Tag[PMTAGSIZE + 1]; /* port monitor's tag */
783 FILE *Fp; /* file pointer for log file */
784 FILE *Tfp; /* file pointer for pid file */
785 char State; /* portmonitor's current state*/
786 main(argc, argv)
788 int argc;
789 char *argv[];
790 {
791 char *istate;
792 strcpy(Tag, getenv("PMTAG"));
793 /*
794 * open up a log file in port monitor's private directory
795 */
796 sprintf(Scratch, "/var/saf/%s/log", Tag);
797 Fp = fopen(Scratch, "a+");
798 if (Fp == (FILE *)NULL)
799 exit(1);
800 log(Fp, "starting");
801 /*
802 * retrieve initial state (either "enabled" or "disabled") and set
803 * State accordingly
804 */
805 istate = getenv("ISTATE");
806 sprintf(Scratch, "ISTATE is %s", istate);
807 log(Fp, Scratch);
808 if (!strcmp(istate, "enabled"))
809 State = PM_ENABLED;
810 else if (!strcmp(istate, "disabled"))
811 State = PM_DISABLED;
812 else {
813 log(Fp, "invalid initial state");
814 exit(1);
815 }
816 sprintf(Scratch, "PMTAG is %s", Tag);
817 log(Fp, Scratch);
818 /*
819 * set up pid file and lock it to indicate that we are active
820 */
821 Tfp = fopen("_pid", "w");
822 if (Tfp == (FILE *)NULL) {
823 log(Fp, "couldn't open pid file");
824 exit(1);
825 }
826 if (lockf(fileno(Tfp), F_TEST, 0) < 0) {
827 log(Fp, "pid file already locked");
828 exit(1);
829 }
830 log(Fp, "locking file");
832 if (lockf(fileno(Tfp), F_LOCK, 0) < 0) {
833 log(Fp, "lock failed");
834 exit(1);
835 }
836 fprintf(Tfp, "%d", getpid());
837 fflush(Tfp);
838 /*
840 * handle poll messages from the sac ... this function never returns
841 */
842 handlepoll();
843 pause();
844 fclose(Tfp);
845 fclose(Fp);
846 }
847 handlepoll()
849 {
850 int pfd; /* file descriptor for incoming pipe */
851 int sfd; /* file descriptor for outgoing pipe */
852 struct sacmsg sacmsg; /* incoming message */
853 struct pmmsg pmmsg; /* outgoing message */
854 /*
855 * open pipe for incoming messages from the sac
856 */
857 pfd = open("_pmpipe", O_RDONLY|O_NONBLOCK);
858 if (pfd < 0) {
859 log(Fp, "_pmpipe open failed");
860 exit(1);
861 }
862 /*
863 * open pipe for outgoing messages to the sac
864 */
865 sfd = open("../_sacpipe", O_WRONLY);
866 if (sfd < 0) {
867 log(Fp, "_sacpipe open failed");
868 exit(1);
869 }
870 /*
871 * start to build a return message; we only support class 1 messages
872 */
873 strcpy(pmmsg.pm_tag, Tag);
874 pmmsg.pm_size = 0;
875 pmmsg.pm_maxclass = 1;
876 /*
877 * keep responding to messages from the sac
878 */
879 for (;;) {
880 if (read(pfd, &sacmsg, sizeof(sacmsg)) != sizeof(sacmsg)) {
881 log(Fp, "_pmpipe read failed");
882 exit(1);
883 }
884 /*
885 * determine the message type and respond appropriately
886 */
887 switch (sacmsg.sc_type) {
888 case SC_STATUS:
889 log(Fp, "Got SC_STATUS message");
890 pmmsg.pm_type = PM_STATUS;
891 pmmsg.pm_state = State;
892 break;
893 case SC_ENABLE:
894 /*note internal state change below*/
895 log(Fp, "Got SC_ENABLE message");
896 pmmsg.pm_type = PM_STATUS;
897 State = PM_ENABLED;
898 pmmsg.pm_state = State;
899 break;
900 case SC_DISABLE:
901 /*note internal state change below*/
902 log(Fp, "Got SC_DISABLE message");
903 pmmsg.pm_type = PM_STATUS;
904 State = PM_DISABLED;
905 pmmsg.pm_state = State;
906 break;
907 case SC_READDB:
908 /*
909 * if this were a fully functional port
910 * monitor it would read _pmtab here
911 * and take appropriate action
912 */
913 log(Fp, "Got SC_READDB message");
914 pmmsg.pm_type = PM_STATUS;
915 pmmsg.pm_state = State;
916 break;
917 default:
918 sprintf(Scratch, "Got unknown message <%d>",
919 sacmsg.sc_type);
920 log(Fp, Scratch);
921 pmmsg.pm_type = PM_UNKNOWN;
922 pmmsg.pm_state = State;
923 break;
924 }
925 /*
926 * send back a response to the poll
927 * indicating current state
928 */
929 if (write(sfd, &pmmsg, sizeof(pmmsg)) != sizeof(pmmsg))
930 log(Fp, "sanity response failed");
931 }
932 }
933 /*
934 * general logging function
935 */
936 log(fp, msg)
937 FILE *fp;
938 char *msg;
939 {
940 fprintf(fp, "%d; %s\n", getpid(), msg);
941 fflush(fp);
942 }
943 The sac.h Header File
947 The following example shows the sac.h header file.
948 /* length in bytes of a utmpx id */
950 # define IDLEN 4
951 /* wild character for utmpx ids */
952 # define SC_WILDC 0xff
953 /* max len in bytes for port monitor tag */
954 # define PMTAGSIZE 14
955 /*
956 * values for rflag in doconfig()
957 */
958 /* don't allow assign operations */
959 # define NOASSIGN 0x1
960 /* don't allow run or runwait operations */
961 # define NORUN 0x2
962 /*
963 * message to SAC (header only). This header is forever fixed. The
964 * size field (pm_size) defines the size of the data portion of the
965 * message, which follows the header. The form of this optional data
966 * portion is defined strictly by the message type (pm_type).
967 */
968 struct pmmsg {
969 char pm_type; /* type of message */
970 unchar_t pm_state; /* current state of pm */
971 char pm_maxclass; /* max message class this port monitor
972 understands */
973 char pm_tag[PMTAGSIZE + 1]; /* pm's tag */
974 int pm_size; /* size of opt data portion */
975 };
976 /*
977 * pm_type values
978 */
979 # define PM_STATUS 1 /* status response */
980 # define PM_UNKNOWN 2 /* unknown message was received */
981 /*
982 * pm_state values
983 */
984 /*
985 * Class 1 responses
986 */
987 # define PM_STARTING 1 /* monitor in starting state */
988 # define PM_ENABLED 2 /* monitor in enabled state */
989 # define PM_DISABLED 3 /* monitor in disabled state */
990 # define PM_STOPPING 4 /* monitor in stopping state */
991 /*
992 * message to port monitor
993 */
994 struct sacmsg {
995 int sc_size; /* size of optional data portion */
996 char sc_type; /* type of message */
997 };
998 /*
999 * sc_type values
1000 * These represent commands that the SAC sends to a port monitor.
1001 * These commands are divided into "classes" for extensibility. Each
1002 * subsequent "class" is a superset of the previous "classes" plus
1003 * the new commands defined within that "class". The header for all
1004 * commands is identical; however, a command may be defined such that
1005 * an optional data portion may be sent in addition to the header.
1006 * The format of this optional data piece is self-defining based on
1007 * the command. The first message sent by the SAC
1008 * will always be a class 1 message. The port monitor response
1009 * indicates the maximum class that it is able to understand. Another
1010 * note is that port monitors should only respond to a message with
1011 * an equivalent class response (i.e. a class 1 command causes a
1012 * class 1 response).
1013 */
1014 /*
1015 * Class 1 commands (currently, there are only class 1 commands)
1016 */
1017 # define SC_STATUS 1 /* status request *
1018 # define SC_ENABLE 2 /* enable request */
1019 # define SC_DISABLE 3 /* disable request */
1020 # define SC_READDB 4 /* read pmtab request */
1021 /*
1022 * `errno' values for Saferrno, note that Saferrno is used by both
1023 * pmadm and sacadm and these values are shared between them
1024 */
1025 # define E_BADARGS 1 /* bad args/ill-formed cmd line */
1026 # define E_NOPRIV 2 /* user not priv for operation */
1027 # define E_SAFERR 3 /* generic SAF error */
1028 # define E_SYSERR 4 /* system error */
1029 # define E_NOEXIST 5 /* invalid specification */
1030 # define E_DUP 6 /* entry already exists */
1031 # define E_PMRUN 7 /* port monitor is running */
1032 # define E_PMNOTRUN 8 /* port monitor is not running */
1033 # define E_RECOVER 9
1034 /* in recovery */
1035 Directory Structure
1039 This section gives a description of the SAF files and directories.
1040 /etc/saf/_sysconfig The per-system configuration script.
1042 /etc/saf/_sactab The SAC's administrative file. Contains
1045 information about the port monitors for
1046 which the SAC is responsible.
1047 /etc/saf/pmtag The home directory for port monitor pmtag.
1050 /etc/saf/pmtag/_config The per-port monitor configuration script
1053 for port monitor pmtag.
1054 /etc/saf/pmtag/_pmtab Port monitor pmtag's administrative file.
1057 Contains information about the services for
1058 which pmtag is responsible.
1059 /etc/saf/pmtag/svctag The file in which the per-service configu‐
1062 ration script for service svctag (available
1063 through port monitor pmtag) is placed.
1064 /etc/saf/pmtag/_pid The file in which a port monitor writes its
1067 process id in the current directory and
1068 places an advisory lock on the file.
1069 /etc/saf/ pmtag /_pmpipe The file in which the port monitor receives
1072 messages from the SAC and ../_sacpipe and
1073 sends return messages to the SAC.
1074 /var/saf/_log The SAC's log file.
1077 /var/saf/pmtag The directory for files created by port
1080 monitor pmtag, for example its log file.
1081
1084 The following administrative commands relate to SAF.
1085 sacadm(1M) port monitor administrative command
1087 pmadm(1M) service administration command
1090
1093 See attributes(5) for descriptions of the following attributes:
1094 ┌─────────────────────────────┬─────────────────────────────┐
1099 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
1100 ├─────────────────────────────┼─────────────────────────────┤
1101 │Availability │SUNWcsr │
1102 └─────────────────────────────┴─────────────────────────────┘
1103
1105 exec(1), sh(1), init(1M), nlsadmin(1M), pmadm(1M), sac(1M), sacadm(1M),
1106 ttyadm(1M), fork(2), doconfig(3NSL), attributes(5)
1107SunOS 5.11 30 Jul1998 saf(1M)