This file: What is cygrunsrv? What does it do? How do I use it? Informative options... Querying a service Removing a service Starting a service Stopping a service Installing a service General Notes Generic Examples (but very informative) Specific Examples (for common cygwin services) ********************************************** What is cygrunsrv? cygrunsrv is an implementation of an NT/W2K service starter, similar to Microsoft's INSTSRV and SRVANY programs, or the FireDaemon program. However, cygrunsrv is a cygwin program itself, so it obviously supports Cygwin applications better. ********************************************** What does it do? cygrunsrv can operate in two basic modes. The first is the 'service management' or 'commandline' mode. This allows you to install and remove a service from the system registry, or to start and stop a previously installed service. The second mode is the 'run a service' or 'daemonize' mode. This mode is reached ONLY via a special entry point called by the Windows Service Mananger -- you can't put cygrunsrv in that mode from the command line. In the 'daemonize' mode, cygrunsrv sets up the environment (according to flags set via the 'commandline' mode). It adds '/bin' to the front of the PATH so that the target service can find cygwin1.dll easily. It (optionally) redirects stdout, stdin, and stderr to log files or to the NT/W2K Event Log (event log access not yet implemented). Finally, cygrunsrv starts the target daemon. ********************************************** How do I use it? As stated earlier, there are four basic operations that cygrunsrv can do in its 'service management' or 'commandline' mode: install a service (-I or --install), remove a service (-R or --remove), start a service (-S or --start), or stop a service (-E or --stop). In addition, the informative options return information about cygrunsrv itself. Each mode is discussed in turn, below: ********************************************** Informative Options cygrunsrv -h cygrunsrv --help print comprehensive help/option listing for cygrunsrv cygrunsrv -v cygrunsrv --version print version information about the cygrunsrv executable ********************************************** Query a service: cygrunsrv -Q cygrunsrv --query reports on the existence and status of the service. Use the --verbose or -V flag to receive extra information. can either specify a local service name, or it can be "server/svc_name" or "server\svc_name" to specify a service on a remote machine. The server name can be given as simple name or as fully qualified domain name (server.example.com). ********************************************** List services installed with cygrunsrv: cygrunsrv -L [server] cygrunsrv --list [server] lists all services that have been installed with cygrunsrv, one per line. You can use this for example to stop all running cygwin services as follows: $ cygrunsrv -L | (while read S; do cygrunsrv -E $S; done) You can combine this with the -V / --verbose option to get full details of each service instead of just names. You can optionally specify a server name to list services installed on a remote machine. The server name can be given as simple name or as fully qualified domain name (server.example.com). ********************************************** Remove a service: cygrunsrv -R cygrunsrv --remove removes the service from the registry can either specify a local service name, or it can be "server/svc_name" or "server\svc_name" to specify a service on a remote machine. The server name can be given as simple name or as fully qualified domain name (server.example.com). ********************************************** Start a service: cygrunsrv -S cygrunsrv --start attempts to start a previously installed service can either specify a local service name, or it can be "server/svc_name" or "server\svc_name" to specify a service on a remote machine. The server name can be given as simple name or as fully qualified domain name (server.example.com). ********************************************** Stop a service: cygrunsrv -E cygrunsrv --stop attempts to stop a previously started service can either specify a local service name, or it can be "server/svc_name" or "server\svc_name" to specify a service on a remote machine. The server name can be given as simple name or as fully qualified domain name (server.example.com). ********************************************** Install a service: At minimum, the following options and arguments MUST be specified (of course, the short options -I and -p can be used instead of the long options --install and --path): cygrunsrv --install svc_name --path /cygwin/style/path/to/daemon.exe Note that the "svc_name" is the name of the key in the registry under which the information for this service is stored. More importantly, it is the name that appears in the Service Manager control panel applet, and is the name that can be used by 'cygrunsrv --start' (or 'net start') to start the service (* see --disp option). Note that the svc_name does not HAVE to be the same as the executable name, but by convention they are usually the same. can either specify a local service name, or it can be "server/svc_name" or "server\svc_name" to specify a service on a remote machine. The server name can be given as simple name or as fully qualified domain name (server.example.com). There are a number of additional, optional arguments that may be specified. ------------------------------- -P, --crs-path Optional path to the cygrunsrv.exe executable. Specifying this can be useful in several situations. On the local machine, the path to cygrunsrv is by default the path to the very executable you execute for the -I command. For testing purposes you could wish to use another cygrunsrv executable than the one which should be used for starting the service. On a remote server, the path to cygrunsrv is by default the path in the system registry key for the Cygwin root directory (what you get when running `mount | grep " / "' on the remote machine), concatentated with "\bin\cygrunsrv.exe". This is not failsafe. It might be better to specify the path to cygrunsrv on the remote machine manually here. The path can be given in POSIX or Win32 notation. For remote services it's advisable to use the Win32 notation. ------------------------------- -a, --args Optional string with command line options which shall be passed to the target service when it is started. This option may only be specified one; to call the target service with two arguments, list both arguments surrounded by quotes. For example, cygrunsrv -I foo -p /usr/bin/bar -a "-D -e" calls with two arguments, as in "/usr/bin/bar -D -e". If you need to specify a single argument which contains spaces, you can protect it with single (') or double (") quotes: (a) cygrunsrv -I foo -p /usr/bin/bar -a "\"foo bar\"" (b) cygrunsrv -I foo -p /usr/bin/bar -a "'foo bar'" (c) cygrunsrv -I foo -p /usr/bin/bar -a '"foo bar"' each result in (a) /usr/bin/bar "foo bar" (b) /usr/bin/bar 'foo bar' (c) /usr/bin/bar "foo bar" (symmetry suggests the following, but it doesn't work. Trust me) cygrunsrv -I foo -p /usr/bin/bar -a '\'foo bar\'' ------------------------------- -e, --env Optional environment strings which are added to the environment when the service is started. You can add up to 255 environment strings using multiple `--env' options. Note that '/bin:' is always appended to the path to allow started applications to find cygwin1.dll. You may also specify PATH=/a/path:/list if you like, but /bin WILL be appended. cygrunsrv -I foo -p /usr/bin/bar -e HOME=/e/services -e TMP=/var/tmp A single level of quoting with either single (') or double (") quotes is allowed: cygrunsrv -I foo -p /usr/bin/bar -e BAR="\"/d/My Documents/services\"" results in an environment where BAR has the value "/d/My Documents/services" *including the quotes* (the \-escaping and the outer quotes are required to protect the command itself from bash). If you don't understand this discussion about quoting, don't worry -- you probably don't need it. ------------------------------- -d, --disp Optional string which contains the display name of the service. The default value is the service name (svc_name). cygrunsrv -I svc_name -p /usr/bin/svc.exe -d baz results in a service whose parameters are stored under the registry key 'svc_name', executes the daemon svc.exe, but shows up in the Services control panel applet with the name 'baz'. You can start/stop the daemon using 'cygrunsrv -S svc_name' or 'net start svc_name' -- but it will report 'The baz service is starting' etc. ------------------------------- -f, --desc Optional service description string. The description string is displayed in the Windows graphical display for starting and stopping the service. ------------------------------- -t, --type [auto|manual] Optional start type of service. Defaults to `auto' (e.g. this service will be automatically started at system bootup). 'manual' means the service must be explicitly started using 'cygrunsrv -S svc_name' ------------------------------- -u, --user Optional user name to start service as. Defaults to SYSTEM account (also known as the 'LocalSystem' account). The user must have the "Logon as a service" privilege. The user name can be given as Cygwin user name as stored in /etc/passwd: $ grep "LocalService" /etc/passwd ls:*:19:0:U-NT AUTHORITY\LocalService,S-1-5-19:/tmp:/bin/false $ cygrunsrv -I svc -p cmd -u ls or it can be given in NT user name notation. The backslash used to separate doamin name and user name can be replaced with a slash. Examples: $ cygrunsrv -I svc -p cmd -u MY_DOMAIN\\user $ cygrunsrv -I svc -p cmd -u MY_DOMAIN/user $ cygrunsrv -I svc -p cmd -u "NT AUTHORITY/LocalService" $ cygrunsrv -I svc -p cmd -u "NT AUTHORITY"\\LocalService ------------------------------- -w, --passwd Optional password for user. Only needed if a user is given. If a user has an empty password, enter `-w ' with no . cygrunsrv -I svc_name -p /usr/bin/svc.exe -u foo -w "" If a user is given but the -w option is not used, then cygrunsrv will ask for a password interactively. Note that the password is stored in encrypted form in the registry. Beginning with Windows XP and 2003 Server, there's a new security setting turned on by default, which disallows starting services for accounts without passwords. When you start the Security Policy MMC Snap-In, you'll find it under Securiy Settings/Local Policies/Security Options. The setting is called "Accounts: Limit local account use of blank password to console logon only." You can disable it, but it's highly discouraged. There's usually no good reason to install a service under an account without password. ------------------------------- -0, --stdin Optional input file used for stdin redirection. Default is /dev/null. ------------------------------- -1, --stdout Optional output file used for stdout redirection. Default is /var/log/.log. ------------------------------- -2, --stderr Optional output file used for stderr redirection. Default is /var/log/.log. (Thus, by default, both stdout and stderr are redirected to /var/log/.log). Note, it may soon be possible to redirect thru a pipe to the logger program (which is part of the inetutils package) so that messages printed by the target service are stored in the NT/W2K Event Application Log. For example, THIS IS NOT YET IMPLEMENTED!!!! cygrunsrv -I svc_name -p /usr/bin/foo.exe \ --stderr "|/usr/bin/logger -p INFO -t svc_name" ------------------------------- -x, --pidfile Optional path for .pid file written by application after fork(). Default is that the application must not fork(). With this option, it is possible to run daemons not providing a (usually Cygwin-specific) option to prevent fork()ing. ------------------------------- -s, --termsig Optional signal to send to service application to stop the service. can be a number or a signal name such as HUP, INT, QUIT, etc. Default is TERM, which is appropriate for most daemons. ------------------------------- -z, --shutsig Optional signal to send to service application to stop the service in case of a system shutdown. This is useful if your service application wants to allow different actions to be taken on a normal service stop and on system shutdown. Note that the --shutsig option only has an effect if you use the --preshutdown or --shutdown option (see there for more information). The default signal on shutdown is the termination signal set with --termsig, TERM otherwise. ------------------------------- -y, --dep Optional name of service that must be started before this new service. The --dep option may be given up to 16 times, listing another dependent service each time. Try to avoid dependency loops: that is, if svc_A depends on svc_B, but svc_B depends on svc_A... ------------------------------- -n, --neverexits Optional flag that causes cygrunsrv to only report a successful shutdown of the service to windows when cygrunsrv itself was told to shutdown and the exec'ed process exited with a zero status. Use this option when the service should only be started or stopped via the Windows service mechanism (e.g. cygrunsrv -E, net stop, or via the services GUI). ------------------------------- -O, --preshutdown -o, --shutdown Optional flags that causes cygrunsrv to terminate the service application during system shutdown. When in effect, cygrunsrv sends the shutdown signal (see --shutsig) to the application process when cygrunsrv learns that the system is shutting down. This gives the application a short time (usually not more than up to 20 secs) to clean up and exit gracefully. Note that each Cygwin process also sends SIGHUP to itself (implicitly) during system shutdown. Starting with Windows Vista/Longhorn, the --preshutdown option allows to terminate the service before the real shutdown takes place, giving the service up to 3 minutes for its shutdown actions. Only one of the --preshutdown/--shutdown options is allowed. If you use --preshutdown on operating systems prior to Windows Vista/Longhorn, it will be silently converted to --shutdown at service runtime. ------------------------------- -i, --interactive Optional flag that allows cygrunsrv to interact with the desktop. When in effect, cygrunsrv can open windows and pop up message boxes. Equivalent to the "Allow service to interact with desktop" box. Cannot be used unless the service runs as SYSTEM. NOTE: The interactive option has not the desired effect anymore, starting with Windows Vista/Longhorn. Interactive services which are allowed to interact with the local desktop are deprecated by Microsoft. To get desktop interaction, your service needs to use other means of interprocess communication between the actual service application and a desktop application running in the user context of the desktop user. ------------------------------- -j, --nohide When running services interactively (see -i, --interactive option above), usually a console window pops up, which has been opened by the service control manager. Beginning with version 0.99, cygrunsrv hides that console window by default. If you need that console window open, use the -j or --nohide option. In that case, cygrunsrv keeps the console window untouched. ********************************************** Information on mounts: Services by default are run as the local system account, not your regular user account. This means that if you have user-mode mounts (i.e. you selected 'Just Me' in setup.exe) the service will not see them and fail to start. Cygrunsrv will now attempt to detect this an warn you if /usr/bin is mounted in user mode. See also . ********************************************** General Notes: There's currently one caveat, though. If the application behaves as a "normal" unix daemon and exits after forking a child, cygrunsrv will immediately stop the service (but the actual daemon keeps running in the background). This means that you cannot then STOP the daemon using cygrunsrv, but you must explicit kill it via 'kill -9 ' If you fail to do this, you will probably see something like this in the Windows Application Event Log: Cygwin Apache : Win32 Process Id = 0xFE : Cygwin Process Id = 0xFE : `Cygwin Apache' service started. immediately followed by Cygwin Apache : Win32 Process Id = 0xFE : Cygwin Process Id = 0xFE : `Cygwin Apache' service stopped. but 'ps -eaf | grep httpd' shows that httpd IS still running. To avoid this problem, you must start the application so that it doesn't fork a daemon but stays resident instead. sshd for example has to be called with the -D option. squid must be called with the -N option. For example, cygrunsrv -I sshd -p /usr/sbin/sshd -a -D cygrunsrv -I squid -p /usr/bin/squid -a -N although other options may be necessary. ********************************************** Generic Examples To install the Cygwin application /bin/foo as service "foo" running under LocalSystem account, no special options: cygrunsrv -I foo -p /bin/foo To install /bin/foo as a service "bar" which requires command line options: cygrunsrv -I bar -p /bin/foo -a '--opt1 --opt2 -x' To install /bin/foo as a service "baz" which requires a command line option which contains spaces: cygrunsrv -I baz -p /bin/foo -a "-x 'this has spaces inside'" or cygrunsrv -I baz -p /bin/foo -a '-x "this has spaces inside"' To install /bin/foo as a service "foo bar" which doesn't automatically startup when the system boots: cygrunsrv -I "foo bar" -p /bin/foo -t manual To install /bin/foo as a service "bongo" which requires settings for the environment variables "ENV_VAR_1" and "ENV_VAR_2" to run correctly: cygrunsrv -I bongo -p /bin/foo -e "ENV_VAR_1=important_1" \ -e "ENV_VAR_2=also_important" To install sshd as service under user `joey' account: cygrunsrv -I "Joey sshd" -p /usr/sbin/sshd -a '-d' -u joey cygrunsrv asks for `joey's password interactively. If one wants to give joey's password (say, "privy23") on the command line: cygrunsrv -I "Joey sshd" -p /usr/sbin/sshd -a '-D' -u joey -w privy23 To start the service `foo': cygrunsrv -S foo To stop the service `foo': cygrunsrv -E foo To uninstall the service `foo': cygrunsrv -R foo ********************************************** Specific Examples Please add suggestions for this list... ------------ postgresql: cygrunsrv --install postmaster \ --path /usr/bin/postmaster \ --args "-D /usr/share/postgresql/data -i" \ --dep ipc-daemon --termsig INT --user postgresql --shutdown ------------ sshd: cygrunsrv --install sshd \ --path /usr/sbin/sshd \ --args -D ------------ xinetd: cygrunsrv --install xinetd \ --pidfile /var/run/xinetd.pid \ --path /usr/sbin/xinetd \ --args "-pidfile /var/run/xinetd.pid" Note that at present, ipc-daemon.exe and inetd.exe contain the appropriate code to run as Windows services WITHOUT the assistance of cygrunsrv. ********************************************** Troubleshooting If the service fails to start, consider whether the service process depends on other services and reinstall the service using the `--dep' parameter to ensure that those other services are running first. In particular, any service application that uses network services (such as socket connections) depends on the "LanmanWorkstation" service; this dependency can be declared as `--dep LanmanWorkstation'. On systems where "LanmanWorkstation" isn't started you can try using a dependency on the "Tcpip" service. In that case just add `--dep Tcpip' to the command line when installing the service. ********************************************** Contact Information For support, contact the cygwin mailing list cygwin@cygwin.com. cygrunsrv was originally created by Corinna Vinschen.