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