Hi Christine,
This is excellent!
I've created a wiki page for updating the FAQs. Please update your FAQs
in the following page.
http://www.genunix.org/wiki/index.php/Solaris10_Tech_FAQ
This webpage has been created to update the FAQs on SMF, zones and
resource management.
Once the FAQs have been reviewed by experts, it'll be made available in
opensolaris.org webpage.
Regards
Ganesh.
Christine Tran wrote:
> Hi,
>
> Here's a list of Q&As I've been putting together, cobbled from my
> notes, questions on smf-discuss and the blogs. I'm most grateful for
> the help from the SMF team, especially David Bustos who supplied the
> questions and reviewed the answers, and Bernd Schemmer who started the
> first SMF FAQ. I don't speak authoritatively on SMF, this is just my
> best effort on taking notes for myself. Please direct any correction
> to smf-discuss and I'll make sure to fix what needs fixing. Thanks.
>
> CT
>
> ------------------------------------------------------------------------
>
> SERVICE MANAGEMENT FACILITY Q&A
> Last modified on 06/02/2006
>
> This Q&A is divided into four sections: General for general description
> of how SMF works and further clarification of official documentation;
> Administrative for how-to questions; Troubleshooting, and Writing SMF
> Manifests. The information on manifest writing covers such a broad range
> of topics that it merits a section of its own.
>
> ------------------------------------------------------------------------------
>
> 1. GENERAL
> 1.1 Short listing of SMF files and directories
> 1.2 Short listing of SMF commands
> 1.3 Short listing of relevant SMF man pages
> 1.4 How permanent is svcadm?
> 1.5 Are milestones the same as run levels?
> 1.6 Where did the output of the rc scripts go?
> 1.7 When I run svcs -a, I see a column labeled STIME. Does that mean
> "Start Time"?
> 1.8 Is SMF integrated with FMA?
> 1.9 Can I make my service depend on a zone?
> 1.10 Why is "Importing service descriptions..." so slow?
> 1.11 svcs shows me a service state with an * next to it, for example,
> online*, what does it mean?
>
>
> 2. ADMINISTRATIVE
> 2.1 How can I allow user X to control service Y?
> 2.2 How do I add a dependency to an existing service?
> 2.3 Why can't I just modify my FMRI manifest and add the dependency?
> 2.4 How do I back up the repository?
> 2.5 How do I take a snapshot of a service's configuration?
> 2.6 Why doesn't "svccfg export apache2" work?
> 2.7 How do I figure out who disabled this service?
> 2.8 How do I make SMF send me an email when a service changes state?
> 2.9 How can I take a snapshot of all of the services on my system, so I
> can check for changes later?
> 2.10 I am in milestone single-user for some diagnostic; I want to enable
> some service but can't.
> 2.11 How do I turn on verbose logging?
> 2.12 How do I delete a service?
>
>
> 3. TROUBLESHOOTING
> 3.1 Why does svcs -x report print/server after a fresh install?
> 3.2 How is it possible that print/server can be disable but still has
> one dependent that is online?
> 3.3 Why is svc.configd is taking up a lot of memory?
> 3.4 Why is svc.configd is taking up a lot of CPU?
> 3.5 My system hangs during boot. What should I do?
> 3.6 I screwed up my service. What should I do?
> 3.7 I screwed up my repository so bad I can't even boot the system to
> restore an old repository backup. What do I do?
> 3.8 svcs -x says service Y was "disabled by an administrator", but I didn't
> disable it.
> 3.9 How come when I set {nis/client, nis/server} to be enabled in site.xml,
> it's not enabled after install?
> 3.10 How come my service hasn't started even though the file: dependency is
> now fulfilled?
> 3.11 Why is network/physical in maintenance?
> 3.12 Why is network/physical hanging?
> 3.13 How come svcs -x doesn't know why my /system/console-login is in
> the offline state?
> 3.14 I just jumpstarted a system and it's complaining that it can't find
> svc:/system/install.
>
>
> 4. WRITING SMF MANIFESTS
> 4.1 How do I write an SMF manifest?
> 4.2 How do I check my manifest for syntax error?
> 4.3 Which filesystem service should I depend on?
> 4.4 What do I need in my manifest in order delegate service administration
> to a user?
> 4.5 What do I need in my manifest to keep my service from restarting
> every time it core dumps or a child process exits?
> 4.6 What are method tokens and how are they used?
>
> ------------------------------------------------------------------------------
>
> 1. GENERAL
>
> 1.1 Short listing of SMF files and directories:
>
> /var/svc: logs, manifests, profiles
> /lib/svc: methods, seed repository, restore_repository script
> /etc/svc: repository.db, repository backups, volatile (a tmpfs)
>
> /var/svc/manifest/site is reserved for manifests specific to your site.
>
>
> 1.2 Short listing of SMF commands:
>
> svcs: service status listing
> svcadm: administrative actions
> svccfg: property modification, can be batch or interactive mode
> svcprop: property reporting, suitable for scripting
> inetadm: administrative and property modification for inetd
> services
> inetconv: convert legacy inetd.conf entries to SMF manifest and
> service
>
> 1.3 Short listing of relevant SMF man pages:
>
> smf(5), svcs(1), svcadm(1M), svccfg(1M), svcprop(1), svc.startd(1M),
> svc.configd(1M), smf_security(5), smf_bootstrap(5), smf_method(5),
> inetadm(1M), inetd(1M).
>
> 1.4 How permanent is svcadm?
>
> Unless the -t switch is used, svcadm enable/disable is persistent
> through reboots, patches, and upgrades. The -t option indicates that
> this specified state is good only until the next reboot.
>
>
> 1.5 Are milestones the same as run levels?
>
> Milestone is a new concept, analogous to run levels, but does not mean
> run level. A milestone defines a specific state of system readiness,
> with a specific set of services enabled. Before SMF, system boot
> progresses from run level S to 3, executing scripts in /etc/rc?.d along
> the way. With SMF, system boot does not progress from milestone to
> milestone, the dependency determines the order of service start.
>
> Except for "none", and "all", milestones show up as services in SMF;
> however, the system can only be in one of the following milestones at
> any time
>
> none, single-user, multi-user, multi-user-default, all.
>
> regardless of the online service state as shown by svcs -a. For
> the system's current milestone, check the options_ovr/milestone
> property of svc:/system/svc/restarter:default
>
> # svcprop -p options_ovr/milestone restarter:default
>
> Other milestones act as readiness declaration for a certain system
> state, for example, svc:/milestone/devices:default is used by SMF to
> indicate that svc:/system/device/fc-fabric:default has finished.
>
>
> 1.6 Where did the output of the rc scripts go?
>
> rc scripts are now started in the analogous milestone, and all
> outputs from them during boot are logged to the milestone service's
> log file in /var/svc/log. For example, scripts in /etc/rc3.d are
> run in milestone multi-user-server, invoked by start method
> /sbin/rc3. The output of those scripts go to
> /var/svc/log/milestone-multi-user-server:default.log.
>
> svc:/milestone/single-user:default starts /etc/rcS.d
> svc:/milestone/multi-user:default starts /etc/rc2.d
> svc:/milestone/multi-user-server:default starts /etc/rc3.d
>
> 1.7 When I run svcs, I see a column labeled STIME. Does that mean
> "Start Time"?
>
> STIME stands for State Time, the time when the service entered that
> state. It is precise to the sub-second, although only the second is
> printed. svcs -a lists services in the order that they finished
> starting. STIME is not authoritative, svcadm refresh will update it.
> To find out when a service was started, you have to look at the log.
>
>
> 1.8 Is SMF integrated with FMA?
>
> No. In particular, the SMF doesn't send any telemetry to fmd.
>
>
> 1.9 Can I make my service depend on a zone?
>
> No, SMF doesn't have the mechanism to support dependencies on zones.
>
>
> 1.10 Why is "Importing service descriptions..." so slow?
>
> It's serial and does a lot of sync'ing (to guard against power
> failure, and such). We're working on it (see CR 6351623).
>
>
> 1.11 svcs shows me a service state with an * next to it, for example,
> online*, what does it mean?
>
> It means the service is still in transition, use svcs -v to see
> the next state.
>
>
> 2. ADMINISTRATIVE
>
> 2.1 How can I allow user X to control service Y?
>
> SMF uses RBAC to delegate service management responsibility. The
> following properties can be set:
>
> - action_authorization: can execute method; allows you to do
> svcadm [enable | disable] -t
> svcadm refresh
> svcadm restart
> svcadm mark maintenance
> svcadm clear
>
> - value_authorization: can change values of existing property; allows
> you to permanently enable or disable a service because in essence,
> you are changing the general/enabled property of the service.
>
> - modify_authorization: can change, add, or delete properties.
>
> See /var/svc/manifest/network/ssh.xml for an example.
>
> The value of these properties, a string, must be added to a user
> security attributed in /etc/user_attr. Here's how to allow user
> jdoe to enable/disable ssh:
>
> /var/svc/manifest/network/ssh.xml:
>
> <property_group name='general' type='framework'>
> <!-- to start stop sshd -->
> <propval name='action_authorization' type='astring'
> value='solaris.smf.manage.ssh' />
> <propval name='value_authorization' type='astring'
> value='solaris.smf.manage.ssh' />
> </property_group>
>
> /etc/user_attr:
> jdoe::::auths=solaris.smf.manage.ssh
>
> The string "solaris.smf.manage.ssh" can be any arbitrary string, but
> "solaris.smf.manage.ssh" is more descriptive than, say, "fooblat".
>
> To see the auction_authorization authorizations for a service, run
>
> # svcprop -p general/action_authorization <FMRI>
>
> If the service has none, you can add one with svccfg
>
> # svccfg -s <FMRI> setprop general/action_authorization = astring: \
> "solaris.smf.manage.service"
> # svcadm refresh <FMRI>
>
> To allow a user to change the properties in certain propperty group,
> give him value_authorization. To allow him to modify, add or remove
> the properties in a certain property group, give him
> modify_authorization.
>
> To allow a user to do manage any service, give him solaris.smf.manage.
> To give a user full control over the repository, give him
> solaris.smf.modify
>
> Give a user authorization by modifying /etc/user_attr
>
> # echo "jdoe::::auths=solaris.smf.manage.service" >> /etc/user_attr
>
> You can see a user's authorizations with "auths jdoe".
>
>
> 2.2 How do I add a dependency to an existing service?
>
> By using svccfg: let's say I want to add a filesystem/local dependency
> to a service:
>
> # svccfg -s <FMRI>
> > addpg myfs-local dependency <-- "myfs-local" is the descriptive name
> > setprop myfs-local/grouping = astring: "require_all"
> > setprop myfs-local/restart_on = astring: "none"
> > setprop myfs-local/type = astring: "service"
> > setprop myfs-local/entities = fmri: "svc:/system/filesystem/local"
> > exit
> # svcadm refresh <FMRI>
>
> If you've made a mistake, invoke editprop, which will launch the vi
> editor. Find your mistake inside vi, correct it, and uncomment the
> hash at the beginning of the command. After writing and quiting vi,
> the command you've uncommented is executed.
>
> Note that svccfg import employs a syntax checker to validate your
> XML manifest. This does not extend to using svccfg to modify service
> properties. svccfg will allow you to make a mistake in the batch or
> interactive mode that would have been caught by svccfg import.
>
>
> 2.3 Why can't I just modify my FMRI manifest and add
> <dependency name='myfs-local'
> grouping='require_all'
> restart_on='none'
> type='service'>
> <service_fmri value='svc:/system/filesystem/local' />
> </dependency>
>
> Never modify manifests in place. This can't be stressed enough.
> Always use svccfg to modify or customize a service. SMF detects
> customizations by comparing current property values with those from
> the last manifest imported. If your customizations are in a manifest,
> then SMF will think that you have no customizations. In a future
> patch or upgrade, SMF may drop in a new manifest and erase all the
> customizations you've added in the manifest.
>
>
> 2.4 How do I back up the repository?
>
> Currently the ability to take repository backup at will does not exist.
> 4 backup copies are taken automatically and kept in /etc/svc. You can
> make copies of /etc/svc/repository.db but there is a risk that such
> a copy won't be self-consistent if svc.configd makes a change during
> the copy.
>
>
> 2.5 How do I take a snapshot of a service's configuration?
>
> Currently you can't take snapshots at will. There is an RFE filed to
> make this possible, see CR 6199307. You can use
> "svccfg export <service>" to get an XML file describing the
> currently running service.
>
>
> 2.6 Why doesn't "svccfg export apache2" work?
>
> svccfg only exports services. In /network/http:apache2, "network"
> is the functional category, "http" is the service, "apache2" is the
> instance. You can export the service using "svccfg export http",
> the exported manifest will include the instance. Work is underway
> to enable svccfg to export instances, see CR 6299665.
>
>
> 2.7 How do I figure out who disabled this service?
>
> Currently SMF does not track who does what.
>
>
> 2.8 How do I make SMF send me an email when a service changes state?
>
> There isn't any way to do this yet.
>
>
> 2.9 How can I take a snapshot of all of the services on my system, so I
> can check for changes later?
>
> There is no ability to take snapshots at will yet. CR 6199307 has
> been filed to allow snapshot-at-will, and CR 6389280 has been filed
> to allow users to compare snapshots. The alternative is to use
> svccfg export to output service properties in XML files and compare
> those, or svccfg archive to get a full service description for all
> services in one XML file. Also see question 2.5.
>
>
> 2.10 I am in milestone single-user for some diagnostic; I want to enable
> some service but can't.
>
> This is propably due to your repository not mounted as writeable, you
> can check this by looking at the output of "mount" and check the
> writeability of the root filesystem.
>
> You can get around this problem by using svcadm enable -t to
> temporarily enable the service. Better yet, use svcadm enable -rt to
> also enable all your service's dependencies all at once.
>
>
> 2.11 How do I turn on verbose logging?
>
> Set the options/logging property of the restarter:
>
> # svccfg -s /system/svc/restarter:default
> > addpg options application
> > setprop options/logging = astring: "verbose"
> > setprop options/type = astring: "framework"
> > exit
> # svcadm refresh /system/svc/restarter:default
>
> Also see question 3.5 for use of boot -m verbose.
>
>
> 2.12 How do I delete a service?
>
> Use "svccfg delete". This will fail if the service is running.
> In that case, either disable the service with svcadm, or use
> "svccfg delete -f". Remove the service manifest. This last step is
> to avoid SMF re-enabling the service in case of a seed repository
> recovery when SMF re-imports manifests.
>
> Warning: Delete services at your own risk. You might inadvertently
> upset a milestone or another service which depends on the service
> you just deleted, and the effect might not be immediately noticeable.
>
>
> 3. TROUBLESHOOTING
>
> 3.1 Why does svcs -x report print/server after a fresh install?
>
> Services which depend on svc:/application/print/server:default are
> delivered as enabled, but svc:/application/print/server:default is
> delivered as disabled. This results in the dependent services being
> placed in the 'offline' state, which svcs -x reports as an error.
>
>
> 3.2 svc:/application/print/server:default actually has 3 dependents.
> Despite it being disabled, only two dependents are offline, one
> dependent (milestone/multi-user) is actually online. How is this
> possible?
>
> There are 4 types of dependencies. One may think of them in terms
> of gradient, how much does a service need from a dependency before it
> considers that dependency satisfied. The relationship print/server
> has with milestone/multi-user is of type "optional_all". This means
> that print/server can be in the disabled state and still allow
> milestone/multi-server to run. The relationship print/server has with
> the other 2 services are of type "require_any" and "require_all",
> which are satisfied when print/server is online or degraded.
>
>
> 3.3 Why is svc.configd is taking up a lot of memory?
>
> You may be running into
> CR 6304200: svc.configd becomes a heavyweight, weighing in at 500MB
> The fix is integrated into a future Update of Solaris 10. The
> workaround is to kill svc.configd, svc.startd will start a new one.
>
>
> 3.4 Why is svc.configd is taking up a lot of CPU?
>
> You may be running into
> CR 6237669: _check_services() SMF logic causing svc.configd overwork.
> If you are frequently mounting NFS filesystems, every mount is causing
> SMF to unnecessarily refresh a set of related services and to consume
> a lot of CPU doing so. This will be fixed in Solaris 10 Update 2.
>
> svc.configd only does work for its clients, and svc.startd is its
> biggest client. If this is not the bug you are running into,
> check svc.startd.
>
> 3.5 My system hangs during boot. What should I do?
>
> You can observe service start messages during boot by using
> boot -m verbose. For a system that hangs during boot, boot to
> milestone "none", login and bring the system to milestone "all",
> watch to see where your system hangs.
>
> ok> boot -m verbose, milestone=none
> (login)
> # svcadm milestone all
>
>
> 3.6 I screwed up my service. What should I do?
>
> If a single service is broken, first run svcs -x <FMRI>, this may tell
> you what has gone wrong. Check the log files in
> /var/svc/log/service-name.log.
>
> SMF keeps a snapshot of the last time your service successfully
> started. As a last resort, you can roll back to that snapshot.
>
> # svccfg -s service:instance
> > selectsnap start
> > revert
> > exit
> # svcadm refresh service:instance
>
>
> 3.7 I screwed up my repository so bad I can't even boot the system to
> restore an old repository backup. What do I do?
>
> If neither boot -s nor boot -m milestone=none provides a shell for you,
> then you'll have to boot net or boot from a CD. Then mount the root
> filesystem and run
>
> # /lib/svc/bin/restore_repository -r /path/to/root
>
>
> 3.8 svcs -x says service Y was "disabled by an administrator", but I didn't
> disable it.
>
> SMF does not record who does what, it assumes that the service was
> disabled by an administrator. Incidentally, you only see this when
> using svcs -x <FMRI>, invocations of svcs or with the -l or -v option
> will just show the the state as being "disabled".
>
>
> 3.9 How come when I set {nis/client, nis/server} to be enabled in site.xml,
> it's not enabled after install?
>
> If you installed your system using jumpstart, the first time your
> system boots, site.xml is applied and then
> /lib/svc/method/sysidtool-system resets the name service according to
> the sysidcfg file, disables {nis/client, nis/server} and undoes what
> site.xml has done. This is a bug, see CR 6421535.
>
> To get around this, create another service that depends on
> sysidtool-system which re-applies site.xml.
>
>
> 3.10 How come my service hasn't started even though the file: dependency is
> now fulfilled?
>
> There is no file event to signal SMF that a file has come online.
> If SMF tries to start your service and finds that a file: dependency
> is not satisfied, it continues to think so forever. See CR 5106165.
>
> The workaround is to run "svcadm refresh". If the file is on a remote
> filesystem, make sure your manifest includes the appropriate filesystem
> dependency to allow your service to find the files it needs before it
> starts.
>
>
> 3.11 Why is network/physical in maintenance?
>
> One possible reason is that you may have aliased your hostname to
> 127.0.0.1, the loopback address, and then used that hostname in your
> /etc/hostname.interface file.
>
>
> 3.12 Why is network/physical hanging?
>
> svc:/network/physical:default is using ifconfig, which tries
> to do a name-service lookup to get the netmasks for the interfaces.
> If nis/client is running, then ypbind will hang, since there are no
> physical interfaces.
>
>
> 3.13 How come svcs -x doesn't know why my /system/console-login is in
> the offline state?
>
> If you boot to milestone "none" and from there go to milestone "all"
> (see question 3.5) without exiting the sulogin shell, svc.startd
> keeps console-login in the offline state. svcs -x sees that all
> of console-login's dependencies are satisfied, and can't figure out
> why console-login is offline. Your system is fine. svc.startd
> will notice when you've logged out of your sulogin shell and will
> start console-login properly after that.
>
> In another situation, if you have a file: dependency which was not
> satisfied when your service start, but the file is present when
> you run svcs -x, SMF reports that it can't determine the reason why
> your service is offline. You should refresh your service (see
> question 3.9).
>
>
> 3.14 I just jumpstarted a system and I get this message after it boots:
>
> svc:/milestone/multi-user-server:default
> (multi-user plus exports milestone)
> State: offline since Wed Feb 08 11:44:58 2006
> Reason: Dependency svc:/system/install is absent.
>
> But I can't find svc:/system/install anywhere.
>
> system/install is an service that gets added to the repository after
> the install is complete, but before the reboot. This service is not
> needed if you build your system using jumpstart, and it is removed
> before the reboot. If your finish script has a reboot call, and your
> system reboots before SMF has a chance to completely remove
> system/install, you will get this.
>
> Don't call reboot in your jumpstart finish script. To fix, use
> svccfg to remove the dependency from multi-user-server milestone.
>
> # svccfg -s multi-user-server listpg
>
> Find the dependency name for svc:/system/install, and delete it.
>
> # svccfg -s multi-user-server delpg <name of dependency>
>
>
> 4. WRITING SMF MANIFESTS
>
> 4.1 How do I write an SMF manifest?
>
> The same way you write an rc script: start with Sun-delivered
> manifests as examples. Copy and cut and paste as you need.
>
> The DTD - Document Type Definition, is
> /usr/share/lib/xml/dtd/service_bundle.dtd.1, and is defined at
> the top of each manifest. You need at least 3 things: the
> service name, the start and stop method, and dependencies.
>
> You can find a collection of manifest written by the SMF user
> community at http://opensolaris.org/os/community/smf/manifests
>
>
> 4.2 How do I check my manifest for syntax error?
>
> svccfg import has a built-in validator, and won't import your manifest
> if it has errors. Use "svccfg validate <XML file>" to check your
> syntax without importing the file. You can also use xmllint:
>
> # xmllint --valid <XML file>
>
>
> 4.3 Which filesystem service should I depend on?
>
> You should at least depend on, directly or indirectly,
> filesystem/minimal. If your service requires one or more files, then
> you should also depend, directly or indirectly, on the filesystem
> service that will make that file available before your service starts.
>
> svcs:/system/filesystem/root /usr is mounted
> svcs:/system/filesystem/usr / and /usr are read-write
> svcs:/system/filesystem/minimal /var, /var/adm, /var/run, and /tmp
> tmp are mounted
> svcs:/system/filesystem/local all other filesystems are mounted
>
>
> 4.4 What do I need in my manifest in order delegate service administration
> to a user?
>
> See question 2.1. You need:
>
> <property_group name='general' type='framework'>
> <propval name='action_authorization' type='astring'
> value='solaris.smf.manage.service' />
> <propval name='value_authorization' type='astring'
> value='solaris.smf.manage.service' />
> </property_group>
>
> modify_authorization are typically given per-property group, instead
> of in the general property group.
>
> Don't forget to modify /etc/user_attr to add the value string
> to the user security profile:
>
> /etc/user_attr:
> jdoe::::auths=solaris.smf.manage.ssh
>
>
> 4.5 What do I need in my manifest to keep my service from restarting
> every time it core dumps or a child process exits?
>
> By default, SMF interprets a core dump or an external signal sent
> to a service as an error and tries to restart the service. To
> instruct SMF to ignore these conditions, add the following to your
> manifest:
>
> <property_group name='startd' type='framework'>
> <propval name='ignore_error' type='astring'
> value='core,signal' />
> </property_group>
>
>
> 4.6 What are method tokens and how are they used?
>
> They are placeholder for service values, and are replaced with their
> values by the svc.startd daemon. They can only be used as parameter
> for method calls (start, stop, or refresh). Method tokens are not
> supported by the delegated restarter inetd.
>
> svc.startd supports the following method tokens:
>
> % %%
> %r Name of the restarter, such as svc.startd
> %m Name of the method, such as start or stop
> %s Name of the service
> %i Name of the instance
> %f FMRI of the instance
> %{prop[:,]} Value(s) of a property.
>
> See the smf_method(5) manpage for more.
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> smf-discuss mailing list
> smf-discuss at opensolaris.org
>
