share/man/man8/pmadm.8

   1 '\" te
   2 .\"  Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PMADM 8 "Nov 10, 1998"
   7 .SH NAME
   8 pmadm \- port monitor administration
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBpmadm\fR \fB-a\fR [\fB-p\fR \fIpmtag\fR | \fB-t\fR \fItype\fR] \fB-s\fR \fIsvctag\fR \fB-i\fR \fIid\fR \fB-m\fR \fIpmspecific\fR \fB-v\fR \fIver\fR
  13      [\fB-f\fR xu]
  14      [\fB-y\fR \fIcomment\fR] [\fB-z\fR \fI script\fR]
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBpmadm\fR \fB-r\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBpmadm\fR \fB-e\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBpmadm\fR \fB-d\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBpmadm\fR \fB-l\fR [\fB-t\fR \fItype\fR | \fB-p\fR \fIpmtag\fR] [\fB-s\fR \fIsvctag\fR]
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBpmadm\fR \fB-L\fR [\fB-t\fR \fItype\fR | \fB-p\fR \fIpmtag\fR] [\fB-s\fR \fIsvctag\fR]
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBpmadm\fR \fB-g\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR [\fB-z\fR \fIscript\fR]
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBpmadm\fR \fB-g\fR \fB-s\fR \fIsvctag\fR \fB-t\fR \fItype\fR \fB-z\fR \fIscript\fR
  50 .fi
  51
  52 .SH DESCRIPTION
  53 .sp
  54 .LP
  55 \fBpmadm\fR is the administrative command for the lower level of the Service
  56 Access Facility hierarchy, that is, for service administration. A port may have
  57 only one service associated with it although the same service may be available
  58 through more than one port. In order to uniquely identify an instance of a
  59 service, the \fBpmadm\fR command must identify both the port monitor or port
  60 monitors through which the service is available (\fB-p\fR or \fB-t\fR) and the
  61 service (\fB-s\fR). See .
  62 .sp
  63 .LP
  64 \fBpmadm\fR performs the following functions:
  65 .RS +4
  66 .TP
  67 .ie t \(bu
  68 .el o
  69 adds or removes a service
  70 .RE
  71 .RS +4
  72 .TP
  73 .ie t \(bu
  74 .el o
  75 enables or disables a service
  76 .RE
  77 .RS +4
  78 .TP
  79 .ie t \(bu
  80 .el o
  81 installs or replaces a per-service configuration script
  82 .RE
  83 .RS +4
  84 .TP
  85 .ie t \(bu
  86 .el o
  87 prints requested service information
  88 .RE
  89 .sp
  90 .LP
  91 Any user on the system may invoke \fBpmadm\fR to request service status
  92 (\fB-l\fR or \fB-L\fR) or to print per-service configuration scripts (\fB-g\fR
  93 without the \fB-z\fR option). \fBpmadm\fR with other options may be executed
  94 only by a privileged user.
  95 .SH OPTIONS
  96 .sp
  97 .LP
  98 The following options are supported:
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fB-a\fR\fR
 103 .ad
 104 .RS 17n
 105 Add a service. \fBpmadm\fR adds an entry for the new service to the port
 106 monitor's administrative file. Because of the complexity of the options and
 107 arguments that follow the \fB-a\fR option, it may be convenient to use a
 108 command script or the menu system to add services.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fB-d\fR\fR
 115 .ad
 116 .RS 17n
 117 Disable a service. Add \fBx\fR to the flag field in the entry for the service
 118 \fIsvctag\fR in the port monitor's administrative file. This is the entry used
 119 by port monitor \fIpmtag\fR. See the \fB-f\fR option, below, for a description
 120 of the flags available.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fB-e\fR\fR
 127 .ad
 128 .RS 17n
 129 Enable a service. Remove \fBx\fR from the flag field in the entry for the
 130 service \fIsvctag\fR in the port monitor administrative file. This is the entry
 131 used by port monitor \fIpmtag\fR. See the \fB-f\fR option, below, for a
 132 description of the flags available.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fB-f\fR \fBxu\fR\fR
 139 .ad
 140 .RS 17n
 141 The \fB-f\fR option specifies one or both of the following two flags which are
 142 then included in the flag field of the entry for the new service in the port
 143 monitor's administrative file. If the \fB-f\fR option is not included, no flags
 144 are set and the default conditions prevail. By default, a new service is
 145 enabled and no \fButmpx\fR entry is created for it. An \fB-f\fR option without
 146 a following argument is illegal.
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBx\fR\fR
 151 .ad
 152 .RS 5n
 153 Do not enable the service \fIsvctag\fR available through port monitor
 154 \fIpmtag\fR.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBu\fR\fR
 161 .ad
 162 .RS 5n
 163 Create a \fButmpx\fR entry for service \fIsvctag\fR available through port
 164 monitor \fIpmtag\fR.
 165 .RE
 166
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fB-g\fR\fR
 173 .ad
 174 .RS 17n
 175 Print, install, or replace a per-service configuration script. The \fB-g\fR
 176 option with a \fB-p\fR option and a \fB-s\fR option prints the per-service
 177 configuration script for service \fIsvctag\fR available through port monitor
 178 \fIpmtag\fR. The \fB-g\fR option with a \fB-p\fR option, a \fB-s\fR option, and
 179 a \fB-z\fR option installs the per-service configuration script contained in
 180 the file \fBscript\fR as the per-service configuration script for service
 181 \fIsvctag\fR available through port monitor \fIpmtag\fR. The \fB-g\fR option
 182 with a \fB- s\fR option, a \fB-t\fR option, and a \fB-z\fR option installs the
 183 file \fBscript\fR as the per-service configuration script for service
 184 \fIsvctag\fR available through any port monitor of type \fBtype\fR. Other
 185 combinations of options with \fB-g\fR are invalid.
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fB-i\fR\fI id\fR\fR
 192 .ad
 193 .RS 17n
 194 \fBid\fR is the identity that is to be assigned to service \fIsvctag\fR when it
 195 is started. \fBid\fR must be an entry in \fB/etc/passwd\fR.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fB-l\fR\fR
 202 .ad
 203 .RS 17n
 204 The \fB-l\fR option requests service information. Used by itself and with the
 205 options described below, it provides a filter for extracting information in
 206 several different groupings.
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fB-l\fR\fR
 211 .ad
 212 .RS 23n
 213 By itself, the \fB-l\fR option lists all services on the system.
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fB\fR\fB-l\fR\fB \fR\fB-p\fR\fB \fR\fIpmtag\fR\fR
 220 .ad
 221 .RS 23n
 222 Lists all services available through port monitor \fIpmtag\fR.
 223 .RE
 224
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fB\fR\fB-l\fR\fB \fR\fB-s\fR\fB \fR\fIsvctag\fR\fR
 229 .ad
 230 .RS 23n
 231 Lists all services with tag \fIsvctag\fR.
 232 .RE
 233
 234 .sp
 235 .ne 2
 236 .na
 237 \fB\fB\fR\fB-l\fR\fB \fR\fB-p\fR\fB \fR\fIpmtag\fR\fB-s\fR\fIsvctag\fR\fR
 238 .ad
 239 .RS 23n
 240 Lists service \fIsvctag\fR.
 241 .RE
 242
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fB\fR\fB-l\fR\fB \fR\fB-t\fR\fB \fR\fItype\fR\fR
 247 .ad
 248 .RS 23n
 249 Lists all services available through port monitors of type \fBtype\fR.
 250 .RE
 251
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fB\fR\fB-l\fR\fB \fR\fB-t\fR\fB \fR\fItype\fR\fB-s\fR\fIsvctag\fR\fR
 256 .ad
 257 .RS 23n
 258 Lists all services with tag \fIsvctag\fR available through a port monitor of
 259 type \fBtype\fR.
 260 .RE
 261
 262 Other combinations of options with \fB-l\fR are invalid.
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fB-L\fR\fR
 269 .ad
 270 .RS 17n
 271 The \fB-L\fR option is identical to the \fB-l\fR option except that output is
 272 printed in a condensed format.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fB-m\fR\fI pmspecific\fR\fR
 279 .ad
 280 .RS 17n
 281 \fIpmspecific\fR is the port monitor-specific portion of the port monitor
 282 administrative file entry for the service.
 283 .RE
 284
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fB-p\fR\fI pmtag\fR\fR
 289 .ad
 290 .RS 17n
 291 Specifies the tag associated with the port monitor through which a service
 292 (specified as \fB\fR\fB-s\fR\fB \fR\fIsvctag\fR) is available.
 293 .RE
 294
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fB-r\fR\fR
 299 .ad
 300 .RS 17n
 301 Remove a service. When \fBpmadm\fR removes a service, the entry for the service
 302 is removed from the port monitor's administrative file.
 303 .RE
 304
 305 .sp
 306 .ne 2
 307 .na
 308 \fB\fB-s\fR\fI svctag\fR\fR
 309 .ad
 310 .RS 17n
 311 Specifies the service tag associated with a given service. The service tag is
 312 assigned by the system administrator and is part of the entry for the service
 313 in the port monitor's administrative file.
 314 .RE
 315
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fB-t\fR\fI type\fR\fR
 320 .ad
 321 .RS 17n
 322 Specifies the port monitor type.
 323 .RE
 324
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fB-v\fR\fI ver\fR\fR
 329 .ad
 330 .RS 17n
 331 Specifies the version number of the port monitor administrative file. The
 332 version number may be given as
 333 .sp
 334 .in +2
 335 .nf
 336 \fB-v\fR \fB\&'\fR\fIpmspec\fR \fB-V\fR
 337 .fi
 338 .in -2
 339 .sp
 340
 341 where \fIpmspec\fR is the special administrative command for port monitor
 342 \fIpmtag\fR. This special command is \fBttyadm\fR for \fBttymon\fR and
 343 \fBnlsadmin\fR for \fBlisten\fR. The version stamp of the port monitor is known
 344 by the command and is returned when \fIpmspec\fR is invoked with a \fB-V\fR
 345 option.
 346 .RE
 347
 348 .sp
 349 .ne 2
 350 .na
 351 \fB\fB-y\fR\fI comment\fR\fR
 352 .ad
 353 .RS 17n
 354 Associate \fIcomment\fR with the service entry in the port monitor
 355 administrative file.
 356 .RE
 357
 358 .sp
 359 .ne 2
 360 .na
 361 \fB\fB-z\fR\fI script\fR\fR
 362 .ad
 363 .RS 17n
 364 Used with the \fB-g\fR option to specify the name of the file that contains the
 365 per-service configuration script. Modifying a configuration script is a
 366 three-step procedure. First a copy of the existing script is made (\fB-g\fR
 367 alone). Then the copy is edited. Finally, the copy is put in place over the
 368 existing script (\fB-g\fR with \fB-z\fR).
 369 .RE
 370
 371 .sp
 372 .LP
 373 Options that request information write the requested information to the
 374 standard output. A request for information using the \fB-l\fR option prints
 375 column headers and aligns the information under the appropriate headings. In
 376 this format, a missing field is indicated by a hyphen. A request for
 377 information in the condensed format using the \fB-L\fR option prints the
 378 information in colon-separated fields; missing fields are indicated by two
 379 successive colons. \fB#\fR is the comment character.
 380 .SH EXAMPLES
 381 .LP
 382 \fBExample 1 \fRAdding a Service to a Port Monitor with the Tag \fBpmtag\fR
 383 .sp
 384 .LP
 385 The following command adds a service to a port monitor with tag \fBpmtag\fR and
 386 gives the service the tag \fBsvctag\fR. The port monitor-specific information
 387 is generated by \fBspecpm\fR. The service defined by \fBsvctag\fR will be
 388 invoked with identity \fBroot\fR.
 389
 390 .sp
 391 .in +2
 392 .nf
 393 pmadm -a -p pmtag -s svctag -i root -m `specpm -a arg1 -b arg2`-v `specpm -V`
 394 .fi
 395 .in -2
 396 .sp
 397
 398 .LP
 399 \fBExample 2 \fRAdding a Service with Service Tab \fBsvctag\fR
 400 .sp
 401 .LP
 402 The following command adds a service with service tag \fBsvctag\fR, identity
 403 \fBguest\fR, and port monitor-specific information generated by \fBspecpm\fR to
 404 all port monitors of type \fBtype\fR:
 405
 406 .sp
 407 .in +2
 408 .nf
 409 pmadm -a -s svctag -i guest -t type -m `specpm -a arg1 -b arg2`-v `specpm -V`
 410 .fi
 411 .in -2
 412 .sp
 413
 414 .LP
 415 \fBExample 3 \fRRemoving a Service
 416 .sp
 417 .LP
 418 The following command removes the service \fBsvctag\fR from port monitor
 419 \fBpmtag\fR:
 420
 421 .sp
 422 .in +2
 423 .nf
 424 pmadm -r -p pmtag -s svctag
 425 .fi
 426 .in -2
 427 .sp
 428
 429 .LP
 430 \fBExample 4 \fREnabling a Service
 431 .sp
 432 .LP
 433 The following command enables the service \fBsvctag\fR available through port
 434 monitor \fBpmtag\fR:
 435
 436 .sp
 437 .in +2
 438 .nf
 439 pmadm -e -p pmtag -s svctag
 440 .fi
 441 .in -2
 442 .sp
 443
 444 .LP
 445 \fBExample 5 \fRDisabling a Service
 446 .sp
 447 .LP
 448 The following command disables the service \fBsvctag\fR available through port
 449 monitor \fBpmtag\fR:
 450
 451 .sp
 452 .in +2
 453 .nf
 454 pmadm -d -p pmtag -s svctag
 455 .fi
 456 .in -2
 457 .sp
 458
 459 .LP
 460 \fBExample 6 \fRListing Status Information
 461 .sp
 462 .LP
 463 The following command lists status information for all services:
 464
 465 .sp
 466 .in +2
 467 .nf
 468 pmadm -l
 469 .fi
 470 .in -2
 471 .sp
 472
 473 .LP
 474 \fBExample 7 \fRListing Status Information
 475 .sp
 476 .LP
 477 The following command lists status information for all services available
 478 through the port monitor with tag \fBports\fR:
 479
 480 .sp
 481 .in +2
 482 .nf
 483 pmadm -l -p ports
 484 .fi
 485 .in -2
 486 .sp
 487
 488 .LP
 489 \fBExample 8 \fRListing Status Information in Condensed Format
 490 .sp
 491 .LP
 492 The following command lists the status information for all services available
 493 through the port monitor with tag \fBports\fR in condensed format:
 494
 495 .sp
 496 .in +2
 497 .nf
 498 pmadm -L -p ports
 499 .fi
 500 .in -2
 501 .sp
 502
 503 .LP
 504 \fBExample 9 \fRListing Status Information for All Services
 505 .sp
 506 .LP
 507 List status information for all services available through port monitors of
 508 type \fBlisten\fR:
 509
 510 .sp
 511 .in +2
 512 .nf
 513 pmadm -l -t listen
 514 .fi
 515 .in -2
 516 .sp
 517
 518 .LP
 519 \fBExample 10 \fRPrinting the per-service Configuration
 520 .sp
 521 .LP
 522 The following command prints the per-service configuration script associated
 523 with the service \fBsvctag\fR available through port monitor \fBpmtag\fR:
 524
 525 .sp
 526 .in +2
 527 .nf
 528 pmadm -g -p pmtag -s svctag
 529 .fi
 530 .in -2
 531 .sp
 532
 533 .SH EXIT STATUS
 534 .sp
 535 .LP
 536 The following exit values are returned:
 537 .sp
 538 .ne 2
 539 .na
 540 \fB\fB0\fR\fR
 541 .ad
 542 .RS 6n
 543 Successful operation.
 544 .RE
 545
 546 .sp
 547 .ne 2
 548 .na
 549 \fB\fB>0\fR\fR
 550 .ad
 551 .RS 6n
 552 Operation failed.
 553 .RE
 554
 555 .SH FILES
 556 .sp
 557 .ne 2
 558 .na
 559 \fB\fB/etc/saf/\fR\fIpmtag\fR\fB/_config\fR\fR
 560 .ad
 561 .RS 26n
 562
 563 .RE
 564
 565 .sp
 566 .ne 2
 567 .na
 568 \fB\fB/etc/saf/\fR\fIpmtag\fR\fB/\fR\fIsvctag\fR\fR
 569 .ad
 570 .RS 26n
 571
 572 .RE
 573
 574 .sp
 575 .ne 2
 576 .na
 577 \fB\fB/var/saf/\fR\fIpmtag\fR\fB/*\fR\fR
 578 .ad
 579 .RS 26n
 580
 581 .RE
 582
 583 .SH SEE ALSO
 584 .sp
 585 .LP
 586 \fBsac\fR(8), \fBsacadm\fR(8), \fBdoconfig\fR(3NSL), \fBattributes\fR(5)