Built-in Command-Line Tools
Apple Remote Desktop includes three powerful command-line tools that can be used
with Send UNIX Command:
networksetup
,
systemsetup
, and
kickstart
. The tools
themselves are embedded within the Apple Remote Desktop client software, and do
not interfere with existing installations of the software on Mac OS X Server.
The locations of two of the tools (
networksetup
and
systemsetup
) are added to the
default shell PATH, so you can access them through Remote Desktop as if they were
installed in one of the standard UNIX tool locations.
The
kickstart
tool is not in the default shell path. It must be activated explicitly at its
location:
/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/
Resources/kickstart
Any command in the Mac OS X Server command-line guide that uses
networksetup
or
systemsetup
can be used in Remote Desktop using the Send UNIX Command task. To
change any settings using these tools, you must run them with root permissions.
The command-line guide can be found at:
www.apple.com/server/documentation/
Using networksetup
The command-line tool
networksetup
is used to configure a client’s network settings.
You can use it to create or modify network locations, change IP addresses, set network
service proxies, and much more. You can find the command-line syntax, explanations,
and an example in the tool’s help prompt by entering the following line in Terminal:
160
Chapter 8
Administering Client Computers
 For Mac OS X 10.3 clients use the following:
/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/
Support/networksetup -help
 For clients with Mac OS X v.10.4 or later, use the following from Send UNIX Command:
networksetup -help
A few of the capabilities of
networksetup
are listed below.
Flag
Description
-listallnetworkservices
Displays a list of all the network services on the server’s hardware
ports. An asterisk (*) denotes that a network service is disabled.
-setmanual
networkservice ip subnet
router
Set the TCP/IP configuration for network service to manual with IP
address set to ip, Subnet Mask set to subnet, and Router address
set to router. Example:
networksetup -setmanual "Built-in Ethernet"
192.168.100.100 255.255.255.0 192.168.100.1
-setdhcp networkservice
[clientid]
Use this command to set the TCP/IP configuration for the specified
network service to use DHCP. The client ID is optional. Specify
“Empty” for [clientid] to clear the DHCP client id. Example:
networksetup -setdhcp "Built-in Ethernet"
-setbootp networkservice
Use this command to set the TCP/IP configuration for the specified
network service to use BOOTP.
networksetup -setbootp "Built-in Ethernet"
-setmanualwithdhcprouter
networkservice ip
Use this command to specify a manual IP address to use for DHCP
for the specified network service. Example:
networksetup -setmanualwithdhcprouter "Built-in
Ethernet" 192.168.100.120
-setdnsservers
networkservice dns1
[dns2]
Use this command to specify the IP addresses of servers you want
the specified network service to use to resolve domain names. You
can list any number of servers (replace dns1, dns2, and so on with
the IP addresses of domain name servers). If you want to clear all
DNS entries for the specified network service, type “empty” in place
of the DNS server names. Example:
networksetup -setdnsservers "Built-in Ethernet"
192.168.100.100 192.168.100.12
-setsearchdomains
networkservice domain1
[domain2]
Use this command to designate the search domain for the
specified network service. You can list any number of search
domains (replace domain1, domain2, and so on with the name of a
local domain). If you want to clear all search domain entries for the
specified network service, type “empty” in place of the domain
name. Example:
networksetup -setsearchdomains "Built-in Ethernet"
company.com corp.com
Chapter 8
Administering Client Computers
161
Any command in the Mac OS X Server command-line guide which uses
networksetup
can be used in Remote Desktop using the Send UNIX Command task.
Using systemsetup
The command-line tool
systemsetup
is used to configure other nonnetwork system
settings. You can use it to query or alter time zones, network time servers, sleep
settings, Energy Saver preferences, Remote Login (SSH) preferences, and more. You will
find the command-line syntax, explanations, and example in the tool’s help prompt by
entering the following line in the Terminal:
/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Support/
systemsetup -help
A few of the capabilities of
systemsetup
are listed below:
-setwebproxy
networkservice domain
portnumber (on | off)
[username password]
Set Web proxy for a network service with domain and port number.
Turns proxy on. Optionally, specify on or off to enable and disable
authenticated proxy support. Specify username and password if
you turn authenticated proxy support on. Example:
networksetup -setwebproxy "Built-In Ethernet"
proxy.company.com 80 on bob mypassword
-help
Displays a list of all the commands available in the Network Setup
Tool, with explanatory information.
Flag
Description
Flag
Description
-setallowpowerbuttontosleepcomputer
(on | off)
Enable or disable whether the power button can
sleep the computer. Example:
systemsetup
-setallowpowerbuttontosleepcomputer
on
-setdate mm:dd:yy
Use this command to set the current month, day,
and year. Example:
systemsetup -setdate 04:15:02
-setlocalsubnetname name
Set Local Hostname to
name
. Example:
systemsetup -setlocalsubnetname LabMac1
-setnetworktimeserver timeserver
Use this command to designate a network time
server. Enter the IP address or DNS name for the
network time server. Example:
systemsetup -setnetworktimeserver
time.apple.com
-setremoteappleevents ( on | off )
Use this command to set whether the server
responds to events sent by other computers (such
as AppleScripts). Example:
systemsetup -setremoreappleevents on
162
Chapter 8
Administering Client Computers
-setremotelogin ( on | off )
Sets remote login (SSH) to either on or off.
Important If you turn off remote login, you won’t
be able to administer the server using SSH for
remote login. Example:
systemsetup -setremotelogin on
-setrestartfreeze ( on | off )
Use this command to specify whether the server
restarts automatically after the system freezes.
Example:
systemsetup -setrestartfreeze on
-setrestartpowerfailure ( on | off )
Use this command to specify whether the server
automatically restarts after a power failure.
Example:
systemsetup -setrestartpowerfailure
on
-setsleep minutes
Sets amount of idle time until computer sleeps.
Specify “Never” or “Off” for computers that should
never sleep. Important: if you set the system to
sleep, you will not be able to administer the
server remotely while it is sleeping. Example:
systemsetup -setsleep 60
-settime hh:mm:ss
Sets the current time. The provided time
argument should be in 24-hour format. Example:
systemsetup -settime 16:20:00
-settimezone timezone
Use this command to set the local time zone. Use
“-listtimezones” to list valid timezone arguments.
Example:
systemsetup -settimezone US/Pacific
-setusingnetworktime ( on | off )
Sets whether using network time is on or off.
Example:
systemsetup -setusingnetworktime on
-setWaitForStartupAfterPowerFailure
seconds
Set the number of seconds after which the
computer will start up after a power failure. The
<seconds> value must be a multiple of 30
seconds. Example:
systemsetup -
setWaitForStartupAfterPowerFailure 30
-setwakeonmodem ( on | off )
Use this command to specify whether or not the
server will wake from sleep when modem activity
is detected. Example:
systemsetup -setwakeonmodem on
-setwakeonnetworkaccess ( on | off )
Use this command to specify whether the server
wakes from sleep when a network admin packet
is sent to it. Example:
systemsetup -setwakeonnetworkaccess
on
Flag
Description
Chapter 8
Administering Client Computers
163
Any command in the Mac OS X Server command-line guide that uses
systemsetup
can
be used in Remote Desktop using the Send UNIX Command task.
Using kickstart
The
kickstart
command-line utility is embedded within the Apple Remote Desktop
client software. It allows you to install, uninstall, activate, configure, and restart
components of Apple Remote Desktop without restarting the computer. You can
configure all the features found in the Remote Desktop section of the Sharing System
Preferences. The
kickstart
utility can be used via SSH to configure remote computers,
including Xserves. The
kickstart
utility is located at:
/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/
Resources/kickstart.
The syntax and list of actions possible with
kickstart
are available by running kickstart
as follows:
$sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/
Resources/kickstart -help
If you are running the kickstart utility through Apple Remote Desktop’s Send UNIX
Command function, you don’t need the full path, just the name
kickstart
and root as
the command’s user.
You can use the
sudo
command with an administrator account to use the
kickstart
utility, or you can use the root user via Send UNIX Command. All commands presented
in this section should be typed as one line of text. It’s OK if the text wraps as you enter
it; just be sure not to enter return characters.
The following are some examples of actions possible with kickstart:
 Activate Remote Desktop sharing, enable access privileges for all users, and restart
the Apple Remote Desktop Agent:
$ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/
Contents/Resources/kickstart -activate -configure -access -on -restart
-agent -privs -all
 Activate Remote Desktop sharing, enable access privileges for the users “admin,”
grant full privileges for the users “admin,” and restart the Apple Remote Desktop
Agent and Menu item:
$ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/
Contents/Resources/kickstart -activate -configure -access -on -users
admin -privs -all -restart -agent -menu
 Activate Remote Desktop sharing, and disable access privileges for all users:
$ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/
Contents/Resources/kickstart -activate -configure -access -off
 Shut down the Apple Remote Desktop Agent process:
$ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/
Contents/Resources/kickstart -agent -stop
164
Chapter 8
Administering Client Computers
 Deactivate Remote Desktop access for a computer:
$ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/
Contents/Resources/kickstart -deactivate -configure -access -off
9
165
9