1svccfg(1M) System Administration Commands svccfg(1M)
2
3
4
6 svccfg - import, export, and modify service configurations
7
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
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
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
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
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
583 EDITOR
584
585 The command to run when the editprop subcommand is used. The
586 default editor is vi(1).
587
588
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
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
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)