scutil.tproj/scutil.8

   1 .\"
   2 .\"     @(#)scutil.8
   3 .\"
   4 .Dd January 23, 2008
   5 .Dt SCUTIL 8
   6 .Os "Mac OS X"
   7 .Sh NAME
   8 .Nm scutil
   9 .Nd Manage system configuration parameters
  10 .Sh SYNOPSIS
  11 .Nm
  12 .Br
  13 .Nm
  14 .Fl -prefs Op preference-file
  15 .Br
  16 .Nm
  17 .Fl r
  18 .Op Fl W
  19 .Bro "" Ar nodename | Ar address | Ar local-address remote-address "" Brc
  20 .Br
  21 .Nm
  22 .Fl w Ar dynamic-store-key Op Fl t Ar timeout
  23 .Br
  24 .Nm
  25 .Fl -get Ar pref
  26 .Br
  27 .Nm
  28 .Fl -set Ar pref Op Ar newval
  29 .Br
  30 .Nm
  31 .Fl -dns
  32 .Br
  33 .Nm
  34 .Fl -proxy
  35 .\".Br
  36 .\".Nm
  37 .\".Fl -net
  38 .Sh DESCRIPTION
  39 Invoked with no options,
  40 .Nm
  41 provides a command line interface to the
  42 .Qq dynamic store
  43 data maintained by
  44 .Xr configd 8 .
  45 Interaction with this data (using the SystemConfiguration.framework
  46 SCDynamicStore APIs) is handled with a set of commands read from
  47 standard input.
  48 A list of the available commands is available by entering the
  49 .Ar help
  50 directive.
  51 .Pp
  52 The
  53 .Fl -prefs
  54 option provides a command line interface to the [raw] stored
  55 preference data.
  56 Interaction with this data (using the SystemConfiguration.framework
  57 SCPreferences APIs) is handled with a set of commands read from
  58 standard input.
  59 A list of the available commands is availble by entering the
  60 .Ar help
  61 directive.
  62 .Pp
  63 The
  64 .Fl r
  65 option provides a means of checking the network reachability of a host, an IP
  66 address, or a pair of local and remote IP addresses.
  67 Network
  68 .Qq reachability
  69 is a term that indicates whether network communication is possible between
  70 the current host and the specified host.
  71 .Pp
  72 The
  73 .Fl w
  74 option provides a means of checking for (and optionally waiting for the
  75 creation of or posting of a notification to) a dynamic store key.
  76 .Pp
  77 The
  78 .Fl -get
  79 and
  80 .Fl -set
  81 options provide a means of reporting and updating a select group of
  82 persistent system preferences.
  83 .Pp
  84 The
  85 .Fl -dns
  86 option reports the current DNS configuration.
  87 The first listed
  88 .Xr resolver 5
  89 configuration is considered to be the
  90 .Qq default
  91 configuration.
  92 Additional
  93 .Qq supplemental
  94 configurations follow.  Those containing a
  95 .Qq domain
  96 name will be used for queries matching the specified domain.
  97 Those without will be used as a
  98 .Qq default
  99 configuration in addition to the first listed.
 100 .Pp
 101 The
 102 .Fl -proxy
 103 option reports the current system proxy configuration.
 104 .\".Pp
 105 .\"Lastly, the
 106 .\".Fl -net
 107 .\"option provides a means of managing the system's network configuration.
 108 .Sh OPTIONS
 109 .Bl -tag -width xx
 110 .It Fl r Oo Fl W Oc Bro "" Ar nodename | Ar address | Ar local-address remote-address "" Brc
 111 Check the network reachability of the specified host name, IP address, or a
 112 pair of local and remote IP addresses.
 113 One or more of the following strings will be reported to standard output.
 114 .Pp
 115 .Bl -tag -width "Transient Connection"
 116 .It Not Reachable
 117 The specified nodename/address cannot be reached using the current network
 118 configuration.
 119 .It Reachable
 120 The specified nodename/address can be reached using the current network
 121 configuration.
 122 .It Transient Connection
 123 The specified nodename/address can be reached via a transient (e.g. PPP)
 124 connection.
 125 .It Connection Required
 126 The specified nodename/address can be reached using the current network
 127 configuration but a connection must first be established.
 128 As an example, this status would be returned for a dialup connection
 129 that was not currently active but could handle network traffic for the
 130 target system.
 131 .It Connection Automatic
 132 The specified nodename/address can be reached using the current network
 133 configuration but a connection must first be established.
 134 Any traffic directed to the specified name/address will initiate the
 135 connection.
 136 .It Local Address
 137 The specified nodename/address is one associated with a network interface
 138 on the system.
 139 .It Directly Reachable Addresss
 140 Network traffic to the specified nodename/address will not go through a
 141 gateway but is routed directly to one of the interfaces on the system.
 142 .El
 143 .Pp
 144 The reachability can also be monitored by specifying the
 145 .Fl W
 146 (watch) option.
 147 This will result in the current status being reported as well as the
 148 status when/if the network configuration changes.
 149 .Pp
 150 A zero exit status will be returned when the reachability status is reported correctly.
 151 A non-zero exit status will be returned if errors are detected with an error reported to standard error.
 152 .It Fl w Ar dynamic-store-key Op Fl t Ar timeout
 153 Check if the specified key exists in the
 154 .Qq dynamic store
 155 data maintained by
 156 .Xr configd 8 .
 157 If present,
 158 .Nm
 159 will return with a zero exit status.
 160 If not present,
 161 .Nm
 162 will wait for the specified time for data to be associated with or a notification
 163 to be posted using the key.
 164 A non-zero exit status will be returned if the key was not created/posted
 165 within the specified time.
 166 .Pp
 167 .Nm
 168 will wait indefinitely if a timeout of 0 seconds is specified.
 169 The default timeout is 15 seconds.
 170 .It Fl -get Ar pref
 171 Retrieves the specified preference.  The current value will be reported on standard output.
 172 .Pp
 173 Supported preferences include:
 174 .Bl -tag -width "LocalHostName" -offset indent
 175 .It ComputerName
 176 The user-friendly name for the system.
 177 .It LocalHostName
 178 The local (Bonjour) host name.
 179 .It HostName
 180 The name associated with
 181 .Xr hostname 1
 182 and
 183 .Xr gethostname 3 .
 184 .El
 185 .It Fl -set Ar pref Op Ar newval
 186 Updates the specified preference with the new value.
 187 If the new value is not specified on the command line then it will be read from standard input.
 188 .Pp
 189 Supported preferences include:
 190 ComputerName
 191 LocalHostName
 192 HostName
 193 .Pp
 194 The
 195 .Fl -set
 196 option requires super-user access.
 197 .It Fl -dns
 198 Reports the current DNS configuration.
 199 .It Fl -proxy
 200 Reports the current proxy configuration.
 201 .\".It Fl -net
 202 .\"Provides a command line interface to the
 203 .\".Qq network configuration .
 204 .\"Interaction with this data (using the SystemConfiguration.framework
 205 .\"SCNetworkConfiguration APIs) is handled with a set of commands read
 206 .\"from standard input.  A list of the available commands is available
 207 .\"by entering the help directive.
 208 .\".Pp
 209 .\"The
 210 .\".Fl -net
 211 .\"option requires super-user access.
 212 .El
 213 .Sh SEE ALSO
 214 .Xr configd 8
 215 .Sh HISTORY
 216 The
 217 .Nm
 218 command appeared in Mac OS X Public Beta.