1svccfg(1M)              System Administration Commands              svccfg(1M)
2
3
4

NAME

6       svccfg - import, export, and modify service configurations
7

SYNOPSIS

9       /usr/sbin/svccfg [-v] [-s FMRI]
10
11
12       /usr/sbin/svccfg [-v] [-s FMRI] subcommand [args]...
13
14
15       /usr/sbin/svccfg [-v] [-s FMRI] -f command-file
16
17

DESCRIPTION

19       The svccfg command manipulates data in the service configuration repos‐
20       itory. svccfg can be invoked interactively, with an individual  subcom‐
21       mand, or by specifying a command file that contains a series of subcom‐
22       mands.
23
24
25       Changes made to an existing service in the repository typically do  not
26       take  effect  for that service until the next time the service instance
27       is refreshed. See the refresh subcommand on the svcadm(1M) man page for
28       more details.
29

OPTIONS

31       The following options are supported:
32
33       -f command-file
34
35           Reads and executes svccfg subcommands from command-file.
36
37
38       -s FMRI
39
40           Selects  the  entity indicated by FMRI (a fault management resource
41           identifier) before executing any subcommands. See smf(5).
42
43
44       -v
45
46           Verbose.
47
48

SUBCOMMANDS

50       Subcommands are divided into the categories specified  in  the  subsec‐
51       tions that follow.
52
53
54       All  subcommands  that  accept FMRIs also accept abbreviated or globbed
55       patterns. Instances and services can be abbreviated by  specifying  the
56       instance  name,  or the trailing portion of the service name. For exam‐
57       ple, given the FMRI:
58
59         svc:/network/smtp:sendmail
60
61
62
63
64       All the following are valid abbreviations:
65
66         sendmail
67         :sendmail
68         smtp
69         smtp:sendmail
70         network/smtp
71
72
73
74
75       While the following are invalid:
76
77         mail
78         network
79         network/smt
80
81
82
83
84       Abbreviated forms of FMRIs are unstable, and  should  not  be  used  in
85       scripts  or  other  permanent tools. If a pattern matches more than one
86       instance or service, an error message  is  printed  and  no  action  is
87       taken.
88
89   General Subcommands
90       end
91       exit
92       quit
93
94           Exits immediately.
95
96
97       repository repfile
98
99           Uses  repfile as a repository. By default, svccfg(1M) uses the sys‐
100           tem repository.
101
102           Use repository only  with  files  from  the  identical  version  of
103           Solaris,  including patches, that you are currently running. Do not
104           use this subcommand with the  system  repository,  /etc/svc/reposi‐
105           tory.db.
106
107
108       set [-v|-V]
109
110           Sets  optional  behavior. If no options are specified, set displays
111           the options currently in effect.
112
113           -v
114
115               Turns on verbose mode.
116
117
118           -V
119
120               Turns off verbose mode.
121
122
123
124   Service Profile Subcommands
125       apply [-n] file
126
127           If  a  file  is  a  service  profile,  properties,  including  gen‐
128           eral/enabled,  that  are  specified in the file are modified in the
129           SMF repository. Not-yet-existent  properties  and  property  groups
130           will  be created. The type of the pre-existing property groups will
131           not be changed by the  profile.  Existing  properties  (as  distin‐
132           guished  from  property  groups) can have their type changed by the
133           profile. Nonexistent services and instances are  ignored.  Services
134           and  instances  modified by the profile will be refreshed. If -n is
135           specified, the profile is processed and no changes are  applied  to
136           the  SMF  repository.  Any  syntax  error found will be reported on
137           stderr and an exit code of 1 will be returned.  See  smf(5)  for  a
138           description  of  service profiles. This command requires privileges
139           to modify properties in the service  and  instance.  See  smf_secu‐
140           rity(5)  for  the privileges required to modify properties. If file
141           is not a service profile, the subcommand fails.
142
143
144       extract [> file]
145
146           Prints a service profile which represents the enabled status of the
147           service  instances in the repository to standard output. The output
148           may be redirected to a file.
149
150
151   Service Manifest Subcommands
152       archive [-a]
153
154           Dumps a full XML service description for all  services,  instances,
155           and  their  persistent  properties in the repository. This does not
156           include transient properties such as service state, and is suitable
157           for a relocatable repository backup.
158
159           Without  the -a option, property groups containing protected infor‐
160           mation (identified by the presence of the read_authorization  prop‐
161           erty—see  smf_security(5))  will be archived without their property
162           values. When the  -a  option  is  specified,  all  values  will  be
163           archived.  An error results if there are insufficient privileges to
164           read these values.
165
166
167       export [-a] service_FMRI [>file]
168
169           The service description for the specified service and its instances
170           is  written  to  standard  output  or redirected to the given file.
171           Dependencies with a boolean "external" property  set  to  true  are
172           omitted  in  the belief that they were created on behalf of another
173           service.
174
175           Without the -a option, property groups containing protected  infor‐
176           mation  (identified by the presence of the read_authorization prop‐
177           erty—see smf_security(5)) will be exported without  their  property
178           values.  When  the  -a  option  is  specified,  all  values will be
179           archived. An error results if there are insufficient privileges  to
180           read these values.
181
182           Note  that  export  requires  a  service  FMRI.  If  you specify an
183           instance (including an abbreviation, such as apache2  or  sendmail,
184           that specifies an instance), the command fails.
185
186
187       import [-V] file
188
189           If  file  is a service manifest, then the services and instances it
190           specifies are imported into the repository. According to the  file,
191           dependencies  may  be  created  in other services. See smf(5) for a
192           description of service manifests. See smf_security(5) for the priv‐
193           ileges required to create and modify service configurations.
194
195           Services  and  instances  in the manifest will be validated against
196           template data in the manifest and the repository, and warnings will
197           be  issued  for  all template violations. See smf_template(5) for a
198           description of templates. If the -V option is specified,  manifests
199           that violate the defined templates will fail to import. In interac‐
200           tive invocations of svccfg, -V is the default behavior.
201
202           For existing services and  instances,  properties  which  have  not
203           changed  since  the  last import snapshot was taken are upgraded to
204           those specified by the manifest. Conflicts (properties  which  have
205           been  changed both in the repository and the manifest) are reported
206           on the standard error stream. svccfg will never upgrade  the  "gen‐
207           eral/enabled" and "general/restarter" properties, since they repre‐
208           sent administrator preference.
209
210
211       inventory file
212
213           If file is determined to be a service manifest, then the  FMRIs  of
214           the services and instances the file describes are printed. For each
215           service, the FMRIs of its instances are displayed before  the  FMRI
216           of the service.
217
218
219       restore
220
221           Restores  the  contents  of  the repository from a full XML service
222           description previously created by the archive  subcommand.  If  the
223           archive  was  generated  without the use of the -a option, the con‐
224           tents of the repository following completion of  the  restore  will
225           not  include  the  values  of  any  read-protected  properties (see
226           smf_security(5)). If these are required, they must be restored man‐
227           ually.
228
229           Restoring an archive which is inconsistent with currently installed
230           software (including  patch  revisions)  might  yield  unpredictable
231           results.  Therefore,  prior to restoring an archive, all system and
232           application software, including any service  manifests,  should  be
233           restored  to  the  same state it was in at the time the archive was
234           made.
235
236
237       validate [file | fmri]
238
239           The validate subcommand can operate on a manifest file, an instance
240           FMRI, or the current instance or snapshot entity selection. When an
241           argument is specified, svccfg will check to see whether the  speci‐
242           fied  file  exists.  If the file exists, it will be validated. If a
243           file of the specified name does not exist, the argument is  treated
244           as  an FMRI pattern. If a conflict arises between a filename and an
245           FMRI, use the svc: and file: prefixes to tell svccfg how to  inter‐
246           pret the argument.
247
248           When  you specify a file, the file is processed in a manner similar
249           to import -V, but no changes are made to  the  repository.  If  any
250           errors  are  detected,  svccfg displays the errors and exits with a
251           nonzero exit status.
252
253           For an instance fmri, instance entity selection, or snapshot entity
254           selection,  the specified instance in its composed form (see "Prop‐
255           erties and Property Groups" in smf(5)) will  be  validated  against
256           template data in the repository. Instance FMRIs and instance entity
257           selections use the "running" snapshot for validation. Warnings will
258           be  issued  for  all template violations. See smf_template(5) for a
259           description of templates.
260
261
262   Entity Selection, Modification, and Navigation Subcommands
263       An "entity" refers to a scope, service, or service instance.
264
265       add name
266
267           A new entity with the given name is created as a child of the  cur‐
268           rent  selection. See smf_security(5) for the privileges required to
269           create entities.
270
271
272       delete [-f] {name | fmri}
273
274           The named child of the current selection or the entity specified by
275           fmri  is  deleted.  Attempts  to  delete  service  instances in the
276           "online" or "degraded" state will fail unless the -f flag is speci‐
277           fied.  If a service or service instance has a "dependents" property
278           group of type "framework", then for each  of  its  properties  with
279           type  "astring" or "fmri", if the property has a single value which
280           names a service or service instance then  the  dependency  property
281           group  in  the  indicated service or service instance with the same
282           name as the property will be deleted. See smf_security(5)  for  the
283           privileges required to delete service configurations.
284
285
286       list [pattern]
287
288           The  child  entities of the current selection whose names match the
289           glob pattern pattern are displayed (see fnmatch(5)).  ':properties'
290           is  also  listed for property-bearing entities, namely services and
291           service instances.
292
293
294       select {name | fmri}
295
296           If the argument names a child of the current selection, it  becomes
297           the current selection. Otherwise, the argument is interpreted as an
298           FMRI and the entity that the argument specifies becomes the current
299           selection.
300
301
302       unselect
303
304           The parent of the current selection becomes the current selection.
305
306
307   Property Inspection and Modification Subcommands
308       addpg name type [flags]
309
310           Adds  a  property group with the given name and type to the current
311           selection. flags is a string of  characters  which  designates  the
312           flags  with  which  to  create  the  property group. 'P' represents
313           SCF_PG_FLAG_NONPERSISTENT   (see   scf_service_add_pg(3SCF)).   See
314           smf_security(5)  for  the  privileges  required  to create property
315           groups.
316
317
318       addpropvalue pg/name [type:] value
319
320           Adds the given value to a property. If type is given and the  prop‐
321           erty  exists, then if type does not agree with the property's type,
322           the subcommand fails. The values may be enclosed in  double-quotes.
323           String  values  containing  double-quotes  or  backslashes  must be
324           enclosed by double-quotes and the contained double-quotes and back‐
325           slashes  must  be quoted by backslashes. Nonexistent properties are
326           created, in which case the type  specifier  must  be  present.  See
327           scf_value_create(3SCF)  for a list of available property types. See
328           smf_security(5) for the privileges required to  modify  properties.
329           The  new  value will be appended to the end of the list of property
330           values associated with the property.
331
332
333       delpg name
334
335           Deletes the property group  name  of  the  current  selection.  See
336           smf_security(5)  for  the  privileges  required  to delete property
337           groups.
338
339
340       delprop pg[/name]
341
342           Deletes the named property group or property of the current  selec‐
343           tion.  See  smf_security(5)  for  the privileges required to delete
344           properties.
345
346
347       delpropvalue pg/name globpattern
348
349           Deletes all values matching the given glob  pattern  in  the  named
350           property. Succeeds even if no values match. See smf_security(5) for
351           the privileges required to modify properties.
352
353
354       describe [-v] [-t] [propertygroup/property]
355
356           Describes either the current or the possible settings.
357
358           When invoked without arguments, describe gives  basic  descriptions
359           (if available) of the currently selected entity and all of its cur‐
360           rently set property groups and properties. A property group or spe‐
361           cific  property  can  be  queried by specifying either the property
362           group name, or the property group name and property name, separated
363           by a slash (/), as an argument.
364
365           The  -v  option gives all information available, including descrip‐
366           tions for current settings, constraints, and other possible setting
367           choices.
368
369           The  -t  option shows only the template data for the selection (see
370           smf_template(5)), and does not display  the  current  settings  for
371           property groups and properties.
372
373
374       editprop
375
376           Comments  of  commands to reproduce the property groups and proper‐
377           ties of the current selection are placed in a  temporary  file  and
378           the  program named by the EDITOR environment variable is invoked to
379           edit it. Upon completion, the commands in the  temporary  file  are
380           executed.  The default editor is vi(1). See smf_security(5) for the
381           privileges required to create, modify, or delete properties.
382
383
384       listpg [pattern]
385
386           Displays the names, types, and flags of property groups of the cur‐
387           rent selection. If an argument is given, it is taken as a glob pat‐
388           tern and only property groups with names which match  the  argument
389           are listed.
390
391           In  interactive mode, a basic description of the property groups is
392           also given.
393
394
395       listprop [pattern]
396
397           Lists property groups and properties of the current selection.  For
398           property  groups,  names,  types, and flags are listed. For proper‐
399           ties, names (prepended by the property group name and a slash (/)),
400           types, and values are listed. See scf_value_create(3SCF) for a list
401           of available property types. If an argument is supplied it is taken
402           as  a  glob  pattern  and  only property groups and properties with
403           names which match the argument are listed.
404
405
406       setenv [-i | -s] [-m method_name] envvar value
407
408           Sets a method environment variable for a  service  or  instance  by
409           changing  the  "environment"  property  in the method_name property
410               group, if that property group has type "method". If method_name
411           is  not  specified  and the -i option is used, the "method_context"
412           property group is used, if an instance is  currently  selected.  If
413           the  -s  option  is  used  and a service is currently selected, its
414           "method_context" property group is used. If the -s option  is  used
415           and  an  instance is currently selected, the "method_context" prop‐
416           erty group of its parent is used. If neither the -i option nor  the
417           -s  option  is  used, the "start" property group is searched for in
418           the currently selected entity and,  if  an  instance  is  currently
419           selected,  its  parent is also searched. If the "inetd_start" prop‐
420           erty group is not located, it is searched for in a similiar manner.
421
422           Once the property is located, all values which  begin  with  envvar
423           followed  by  a  "="  are  removed, and the value "envvar=value" is
424           added. See smf_security(5) for the privileges  required  to  modify
425           properties.
426
427
428       setprop pg/name = [type:] value
429       setprop pg/name = [type:] ([values ...])
430
431           Sets  the  name  property  of  the pg property group of the current
432           selection to the given values  of  type  type.  See  scf_value_cre‐
433           ate(3SCF)  for  a list of available property types. If the property
434           already exists and the type disagrees with the existing type on the
435           property,  the  subcommand fails. Values may be enclosed in double-
436           quotes. String values which contain  double-quotes  or  backslashes
437           must  be  enclosed by double-quotes and the contained double-quotes
438           and backslashes must be quoted by backslashes. If the  named  prop‐
439           erty  does  not exist, it is created, as long as the type is speci‐
440           fied. See smf_security(5) for the privileges required to create  or
441           modify  properties.  Multiple values will be stored in the order in
442           which they are specified.
443
444
445       unsetenv [-i | -s] [-m method_name] envvar value
446
447           Removes a method environment variable for a service or instance  by
448           changing  the  "environment"  property  in the method_name property
449               group, if that property group has type "method". If method_name
450           is  not  specified  and the -i option is used, the "method_context"
451           property group is used, if an instance is  currently  selected.  If
452           the  -s  option  is  used  and a service is currently selected, its
453           "method_context" property group is used. If the -s option  is  used
454           and  an  instance is currently selected, the "method_context" prop‐
455           erty group of its parent is used. If neither the -i option nor  the
456           -s  option  is  used, the "start" property group is searched for in
457           the currently selected entity and,  if  an  instance  is  currently
458           selected,  its  parent is also searched. If the "inetd_start" prop‐
459           erty group is not located, it is searched for in a similiar manner.
460
461           Once the property is located, all values which  begin  with  envvar
462           followed by "=" are removed. See smf_security(5) for the privileges
463           required to modify properties.
464
465
466   Snapshot Navigation and Selection Subcommands
467       listsnap
468
469           Displays snapshots available for the currently selected instance.
470
471
472       revert [snapshot]
473
474           Reverts the properties of the currently selected instance  and  its
475           service  to those recorded in the named snapshot. If no argument is
476           given, use the currently selected snapshot and deselect it on  suc‐
477           cess.  The  changed  property  values  can  be  made active via the
478           refresh subcommand of svcadm(1M). See smf_security(5) for the priv‐
479           ileges required to change properties.
480
481
482       selectsnap [name]
483
484           Changes  the  current snapshot to the one named by name. If no name
485           is specified, deselect the currently selected  snapshot.  Snapshots
486           are read-only.
487
488
489   Instance Subcommands
490       refresh
491
492           Commit  the  values  from  the current configuration to the running
493           snapshot, making them available for use by the  currently  selected
494           instance.  If the repository subcommand has not been used to select
495           a repository, direct the instance's restarter to reread the updated
496           configuration.
497
498

EXAMPLES

500       Example 1 Importing a Service Description
501
502
503       The  following  example  imports  a service description for the seismic
504       service in the XML manifest specified on the command line.
505
506
507         # svccfg import /var/svc/manifest/site/seismic.xml
508
509
510
511
512       Note that the manifest must follow the format specified in service_bun‐
513       dle(4).
514
515
516       Example 2 Exporting a Service Description
517
518
519       To export a service description on the local system:
520
521
522         # svccfg export dumpadm >/tmp/dump.xml
523
524
525
526       Example 3 Deleting a Service Instance
527
528
529       To delete a service instance:
530
531
532         # svccfg delete network/inetd-upgrade:default
533
534
535
536       Example 4 Checking Properties in an Alternate Repository
537
538
539       To  examine the state of a service's properties after loading an alter‐
540       nate repository, use the sequence of commands shown  below.  One  might
541       use  such  commands,  for  example,  to determine whether a service was
542       enabled in a particular repository backup.
543
544
545         # svccfg
546         svc:> repository /etc/svc/repository-boot
547         svc:> select telnet:default
548         svc:/network/telnet:default> listprop general/enabled
549         general/enabled  boolean  false
550         svc:/network/telnet:default> exit
551
552
553
554       Example 5 Enabling Debugging
555
556
557       To modify  LD_PRELOAD  for  a  start  method  and  enable  the  use  of
558       libumem(3LIB) with debugging features active:
559
560
561         $ svccfg -s system/service setenv LD_PRELOAD libumem.so
562         $ svccfg -s system/service setenv UMEM_DEBUG default
563
564
565
566       Example 6 Using describe Subcommand
567
568
569       The following command illustrates the use of the describe subcommand.
570
571
572         # svccfg -s console-login describe ttymon
573         ttymon                      application
574         ttymon/device               astring  /dev/console
575            terminal device to be used for the console login prompt
576         ttymon/label                astring  console
577            appropriate entry from /etc/ttydefs
578            ...
579
580
581

ENVIRONMENTAL VARIABLES

583       EDITOR
584
585           The  command  to  run  when  the  editprop  subcommand is used. The
586           default editor is vi(1).
587
588

EXIT STATUS

590       The following exit values are returned:
591
592       0
593
594           Successful execution.
595
596
597       1
598
599           One or more subcommands resulted in  failure.  Error  messages  are
600           written to the standard error stream.
601
602
603       2
604
605           Invalid command line options were specified.
606
607

ATTRIBUTES

609       See attributes(5) for descriptions of the following attributes:
610
611
612
613
614       ┌─────────────────────────────┬─────────────────────────────┐
615       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
616       ├─────────────────────────────┼─────────────────────────────┤
617       │Availability                 │SUNWcsu                      │
618       ├─────────────────────────────┼─────────────────────────────┤
619       │Interface Stability          │See below.                   │
620       └─────────────────────────────┴─────────────────────────────┘
621
622
623       The  interactive output is Uncommitted. The invocation and non-interac‐
624       tive output are Committed.
625

SEE ALSO

627       svcprop(1),   svcs(1),   svcadm(1M),   svc.configd(1M),   libscf(3LIB),
628       libumem(3LIB),  scf_service_add_pg(3SCF),  scf_value_create(3SCF), con‐
629       tract(4),   service_bundle(4),   attributes(5),   fnmatch(5),   smf(5),
630       smf_method(5), smf_security(5), smf_template(5)
631
632
633
634SunOS 5.11                        29 Jun 2009                       svccfg(1M)
Impressum