mirrors/winsw
1
0
Fork 0
mirror of https://github.com/winsw/winsw.git synced 2025-12-10 18:37:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

Rename docs for SEO

Browse Source
This commit is contained in:
NextTurn
2020-02-04 00:00:00 +08:00
committed by Next Turn
parent 700f45cb84
commit f43e3bb6ab
20 changed files with 43 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/deferred-file-operations.md Normal file
View File

@@ -0,0 +1,22 @@
# Deferred file operations
To support self updating services, winsw offers a mechanism to perform file operations before the process you specified in the configuration file gets launched.
This is often necessary because Windows prevents a file from being overwritten while it's in use.
To perform file operations, write a text file (in the UTF-8 encoding) at *myapp.copies*
(that is, it's in the same directory as *myapp.xml* and *myapp.exe* but with a different file extension),
and for each operation add one line:
* To move a file, write a line `src>dst`. If the `dst` file already exists it will be overwritten.
The success or failure of these operations will be recorded in the event log.
`src` and `dst` should be the full path to file, or you will see failed to copy file.
example:
```
c:\soft\sshd.exe.new>c:\bin\ssh.exe
```
The `<download>` element in the configuration file also provides an useful building block for a self updating service.

45
docs/developer/project-structure.md Normal file
View File

@@ -0,0 +1,45 @@
# Project structure
:movie_camera: You can find the code dive session recorded video [here](https://youtu.be/_adhRj19ESY).
```
|_ docs
|_ eng
|_ samples
|_ src
|_ Core
| |_ ServiceWrapper
| |_ Main.cs
| |_ WinSWCore
| |_ ServiceDescriptor.cs
| |_ Configurations
| |_ Extensions
|_ Plugins
|_ Test/winswTest
```
## :open_file_folder: samples
This folder contains templates for configuration files. *sample-minimal.xml* contains a template for mandatory configurations and *sample-complete.xml* contains all possible configurations with documentation.
## :open_file_folder: Core
## :notebook: ServiceWrapper
This is the main executable project. This contains the main.cs which is the entry point of the project and contains some features for logging.
### :page_facing_up: Main.cs
This file contains the entry point of the program (Main method). This file includes the main flow of the program and has implemented the logics for command line arguments. You can find more details about command line arguments [here](../../README.md#usage).
## :notebook: WinSWCore
This is the main component of the project. This contains the most important logics of the project such as ServiceDescriptor.cs, Extension api, configurations, etc.
### :page_facing_up: ServiceDescriptor.cs
This contains the logics for extracting configurations from XML file. The `ServiceDescriptor` class gets XML file as an argument. Currently configuratinos are retrieved on demand.
## :open_file_folder: Configuration
This contains the interface for the configurations. The `IWinSWConfiguration.cs` interface contains all configurations and `DefaultSettings.cs` contains default values for the configurations.

7
docs/exe-config-file.md Normal file
View File

@@ -0,0 +1,7 @@
# EXE configuration file
In addition to the [XML configuration file](xml-config-file.md), WinSW uses a standard .NET *WinSW.exe.config* file, which allows setting up some custom settings.
Use-cases:
* Managing Logging levels of log4j
* etc.

33
docs/extensions/extensions.md Normal file
View File

@@ -0,0 +1,33 @@
# WinSW extensions
Starting from WinSW 2.0, the wrapper provides an internal extension engine and several extensions.
These extensions allow to alter the behavior of the Windows service in order to setup the required service environment.
## Available extensions
* [Shared Directory Mapper](shared-directory-mapper.md) - Allows mapping shared drives before starting the executable
* [Runaway Process Killer](runaway-process-killer.md) - Termination of processes started by the previous runs of WinSW
## Developer guide
In WinSW v2 the extension does not support inclusion of external extension DLLs.
### Adding external extensions
The only way to create an external extension is to create a new extension DLL and
then to merge this DLL into the executable using tools like `ILMerge`.
See the example in `src/Core/ServiceWrapper/winsw.csproj`.
Generic extension creation guideline:
* Extension DLL should reference the `WinSWCore` library.
* The extension should extend the `AbstractWinSWExtension` class.
* The extension then can override event handlers offered by the upper class.
* The extension should implement the configuration parsing from the `XmlNode`.
* The extension should support disabling from the configuration file.
WinSW engine will automatically locate your extension using the class name in the [XML configuration file](../xml-config-file.md).
See configuration samples provided for the extensions in the core.
For extensions from external DLLs, the `className` field should also specify the assembly name.
It can be done via fully qualified class name or just by the `${CLASS_NAME}, ${ASSEMBLY_NAME}` declaration.
Please note that in the current versions of WinSW v2 the binary compatibility of extension APIs **is not guaranteed**.

49
docs/extensions/runaway-process-killer.md Normal file
View File

@@ -0,0 +1,49 @@
# Runaway Process Killer extension
In particular cases Windows service wrapper may leak the process after the service completion.
It happens when WinSW gets terminated without executing the shutdown logic.
Examples: force kill of the service process, .NET Runtime crash, missing permissions to kill processes or a bug in the logic.
Such runaway processes may conflict with the service process once it restarts.
This extension allows preventing it by running the runaway process termination on startup before the executable gets started.
Since: WinSW 2.0.
## Usage
The extension can be configured via the [XML configuration file](../xml-config-file.md). Configuration sample:
```xml
<?xml version="1.0" encoding="utf-8" ?>
<service>
<id>sampleService</id>
<name>Sample service</name>
<description>This is a stub service.</description>
<executable>%BASE%\sleep.bat</executable>
<arguments></arguments>
<log mode="roll"></log>
<extensions>
<!-- This is a sample configuration for the RunawayProcessKiller extension. -->
<extension enabled="true"
className="winsw.Plugins.RunawayProcessKiller.RunawayProcessKillerExtension"
id="killOnStartup">
<!-- Absolute path to the PID file, which stores ID of the previously launched process. -->
<pidfile>%BASE%\pid.txt</pidfile>
<!-- Defines the process termination timeout in milliseconds.
This timeout will be applied multiple times for each child process.
After the timeout WinSW will try to force kill the process.
-->
<stopTimeout>5000</stopTimeout>
</extension>
</extensions>
</service>
```
## Notes
* The current implementation of the the extension checks only the root process (started executable)
* If the runaway process is detected the entire, the entire process tree gets terminated
* WinSW gives the runaway process a chance to the gracefully terminate.
If it does not do it within the timeout, the process will be force-killed.
* If the force kill fails, the WinSW startup continues with a warning.

38
docs/extensions/shared-directory-mapper.md Normal file
View File

@@ -0,0 +1,38 @@
# Shared Directory Mapper extension
By default Windows does not establish shared drive mapping for services even if it is configured in the Windows service profile.
And sometimes it is impossible to workaround it due to the domain policies.
This extension allows mapping external shared directories before starting up the executable.
Since: WinSW 2.0.
## Usage
The extension can be configured via the [XML configuration file](../xml-config-file.md).
Configuration sample:
```xml
<?xml version="1.0" encoding="utf-8" ?>
<service>
<id>sampleService</id>
<name>Sample service</name>
<description>This is a stub service.</description>
<executable>%BASE%\sleep.bat</executable>
<arguments></arguments>
<log mode="roll"></log>
<extensions>
<extension enabled="true" className="winsw.Plugins.SharedDirectoryMapper.SharedDirectoryMapper" id="mapNetworDirs">
<mapping>
<map enabled="false" label="N:" uncpath="\\UNC"/>
<map enabled="false" label="M:" uncpath="\\UNC2"/>
</mapping>
</extension>
</extensions>
</service>
```
## Notes
* If the extension fails to map the drive, the startup fails

51
docs/installation.md Normal file
View File

@@ -0,0 +1,51 @@
# Installation guide
This page provides WinSW installation guidelines for different cases.
## Installation steps
In order to setup WinSW, you commonly need to perform the following steps:
1. Take *WinSW.exe* from the distribution, and rename it to your taste (such as *myapp.exe*)
1. Write *myapp.xml* (see the [XML config file specification](xml-config-file.md) for more details)
1. Place those two files side by side, because that's how WinSW discovers its configuration.
1. Run `myapp.exe install <OPTIONS>` in order to install the service wrapper.
1. Run `myapp.exe start` to start the service.
There are some details for each step available below.
## Installation step details
### Step 2. Configuration file
You write the configuration file that defines your service.
The example below is a primitive example being used in the Jenkins project:
```xml
<service>
<id>jenkins</id>
<name>Jenkins</name>
<description>This service runs Jenkins continuous integration system.</description>
<env name="JENKINS_HOME" value="%BASE%"/>
<executable>java</executable>
<arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
<log mode="roll"></log>
</service>
```
The full specification of the configuration file is available [here](xml-config-file.md).
### Step 3. Service registration
You can then install the service like:
```
myapp.exe install <OPTIONS>
```
... and you can use the exit code from these processes to determine whether the operation was successful.
Possible exit codes are described [here](https://docs.microsoft.com/windows/win32/cimwin32prov/create-method-in-class-win32-service#return-value).
Beyond these error codes, all the non-zero exit code should be assumed as a failure.
The Installer can be also started with the `/p` option.
In such case it will prompt for an account name and password, which should be used as a service account.

115
docs/logging-and-error-reporting.md Normal file
View File

@@ -0,0 +1,115 @@
# Logging and error reporting
## Logging
Winsw supports several different ways to capture stdout and stderr from the process you launch.
## Log directory
The `<logpath>` element specifies the directory in which the log files are created. If this element is absent, it'll default to the same directory where the configuration file resides.
## Append mode (default)
In this mode, *myapp.out.log* and *myapp.err.log* (where *myapp* is the base name of the executable and the configuration file) are created and outputs are simply appended to these files. Note that the file can get quite big.
```xml
<log mode="append"/>
```
## Reset mode
Works like the append mode, except that every time the service starts, the old log files are truncated.
```xml
<log mode="reset"/>
```
## Ignore mode
Throw away stdout and stderr, and do not produce any log files at all.
```xml
<log mode="none"/>
```
## Roll mode
Works like the append mode, but in addition, if the log file gets bigger than a set size, it gets rolled to *myapp.1.out.log*, *myapp.2.out.log* and so on. The nested `<sizeThreshold>` element specifies the rotation threshold in KB (defaults to 10MB), and the nested `<keepFiles>` element specifies the number of rolled files to keep (defaults to 8.)
```xml
<log mode="roll-by-size">
<sizeThreshold>10240</sizeThreshold>
<keepFiles>8</keepFiles>
</log>
```
## Roll by time mode
Works like the roll mode, except that instead of using the size as a threshold, use the time period as the threshold.
This configuration must accompany a nested `<pattern>` element, which specifies the timestamp pattern used as the log file name.
```xml
<log mode="roll-by-time">
<pattern>yyyyMMdd</pattern>
</log>
```
The syntax of the pattern string is specified by [DateTime.ToString(String)](https://docs.microsoft.com/dotnet/api/system.datetime.tostring#System_DateTime_ToString_System_String_).
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`.
## Roll by size and time mode
Works in a combination of roll size mode and roll time mode, if the log file gets bigger than a set size, it gets rolled using `<pattern>` provided.
```xml
<log mode="roll-by-size-time">
<sizeThreshold>10240</sizeThreshold>
<pattern>yyyyMMdd</pattern>
<autoRollAtTime>00:00:00</autoRollAtTime>
</log>
```
The syntax of the pattern string is specified by [DateTime.ToString(String)](https://docs.microsoft.com/dotnet/api/system.datetime.tostring#System_DateTime_ToString_System_String_).
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`.
The syntax of the autoRollAtTime is specified by [TimeSpan.ToString(String)](https://docs.microsoft.com/dotnet/api/system.timespan.tostring#System_TimeSpan_ToString_System_String_).
For example, in the above example, at the start of the day it will roll the file over.
### Automatic archiving of logs
:warning: This feature is reported to be broken in recent WinSW versions.
It is a potential subject for removal.
```xml
<log mode="roll-by-size-time">
<zipOlderThanNumDays>5</zipOlderThanNumDays>
<zipDateFormat>yyyyMM</zipDateFormat>
</log>
```
The `zipOlderThanNumDays` can only be used in conjection with autoRollAtTime, provide the number of days of files to keep.
```xml
<log mode="roll-by-size-time">
<autoRollAtTime>00:00:00</autoRollAtTime>
<zipOlderThanNumDays>5</zipOlderThanNumDays>
</log>
```
The zipDateFormat can only be used in conjection with autoRollAtTime, provide the zip file format using the [TimeSpan.ToString(String)](https://docs.microsoft.com/dotnet/api/system.timespan.tostring#System_TimeSpan_ToString_System_String_).
```xml
<log mode="roll-by-size-time">
<autoRollAtTime>00:00:00</autoRollAtTime>
<zipDateFormat>yyyyMM</zipDateFormat>
</log>
```
## Error reporting
WinSW uses WMI underneath, and as such it uses its error code as the exit code.
For the complete list of exit codes, see [return values of the Create method of the Win32_Service class](https://docs.microsoft.com/windows/win32/cimwin32prov/create-method-in-class-win32-service#return-value).
When winsw is running as a service, more detailed error information is reported to the Windows event log.

15
docs/selfRestartingService.md Normal file
View File

@@ -0,0 +1,15 @@
# Self-restarting Windows services
## Restart from the spawned process
To support self-restarting services, winsw exposes `WINSW_EXECUTABLE` environment variable into the forked process,
which refers to the full path of *WinSW.exe* that's managing the service.
To restart the service from within, execute `%WINSW_EXECUTABLE% restart!`.
Note that you are invoking `restart!` command, not `restart` command.
This hidden command is a flavor of the `restart` operation,
where winsw creates another winsw process in a separate process group,
and restarts the service from there.
This additional indirection is necessary because Windows Service Control Manager (SCM) will kill child processes recursively when it stops a service.
SCM doesn't provide the restart operation as an atomic operation either, so winsw implements restart by a sequence of stop and start.
The second winsw process in a separate process group ensures that winsw can survive this massacre to execute the start call.

354
docs/xml-config-file.md Normal file
View File

@@ -0,0 +1,354 @@
# XML configuration file
This page describes the configuration file, which controls the behavior of the Windows service.
You can find configuration file samples in the [samples](../samples) directory of the source code repository.
Actual samples are being also published as a part of releases on GitHub and NuGet.
## File structure
The root element of this XML file must be `<service>`, and it supports the following child element.
Example:
```xml
<service>
<id>jenkins</id>
<name>Jenkins</name>
<description>This service runs Jenkins continuous integration system.</description>
<env name="JENKINS_HOME" value="%BASE%"/>
<executable>java</executable>
<arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
<log mode="roll"></log>
</service>
```
## Environment variable expansion
Configuration XML files can include environment variable expansions of the form `%Name%`.
Such occurrences, if found, will be automatically replaced by the actual values of the variables.
If an undefined environment variable is referenced, no substitution occurs.
Also, the service wrapper sets the environment variable `BASE` by itself, which points to a directory that contains the renamed *WinSW.exe*.
This is useful to refer to other files in the same directory.
Since this is an environment variable by itself, this value can be also accessed from the child process launched from the service wrapper.
## Configuration entries
### id
Specifies the ID that Windows uses internally to identify the service.
This has to be unique among all the services installed in a system,
and it should consist entirely out of alpha-numeric characters.
### name
Short display name of the service, which can contain spaces and other characters.
This shouldn't be too long, like `<id>`, and this also needs to be unique among all the services in a given system.
### description
Long human-readable description of the service.
This gets displayed in Windows service manager when the service is selected.
### executable
This element specifies the executable to be launched.
It can be either absolute path, or you can just specify the executable name and let it be searched from `PATH` (although note that the services often run in a different user account and therefore it might have different `PATH` than your shell does.)
### startmode
This element specifies the start mode of the Windows service.
It can be one of the following values: Boot, System, Automatic, or Manual.
For more information, see the [ChangeStartMode method](https://docs.microsoft.com/windows/win32/cimwin32prov/changestartmode-method-in-class-win32-service).
The default value is `Automatic`.
### delayedAutoStart
This Boolean option enables the delayed start mode if the `Automatic` start mode is defined.
For more information, see [Startup Processes and Delayed Automatic Start](https://techcommunity.microsoft.com/t5/ask-the-performance-team/ws2008-startup-processes-and-delayed-automatic-start/ba-p/372692).
Please note that this startup mode will not take affect on old Windows versions older than Windows 7 and Windows Server 2008.
Windows service installation may fail in such case.
```xml
<delayedAutoStart/>
```
### depend
Specify IDs of other services that this service depends on.
When service `X` depends on service `Y`, `X` can only run if `Y` is running.
Multiple elements can be used to specify multiple dependencies.
```xml
<depend>Eventlog</depend>
<depend>W32Time</depend>
```
### logging
Optionally set a different logging directory with `<logpath>` and startup `mode`: append (default), reset (clear log), ignore, roll (move to `\*.old`).
See the [Logging and error reporting](logging-and-error-reporting.md) page for more info.
### Arguments
`<argument>` element specifies the arguments to be passed to the executable.
Winsw will quote each argument if necessary, so do not put quotes in `<argument>` to avoid double quotation.
```xml
<argument>arg1</argument>
<argument>arg2</argument>
<argument>arg3</argument>
```
`<arguments>` element can be used instead to specify the whole command line in a single element.
### stopargument/stopexecutable
~~When the service is requested to stop, winsw simply calls [TerminateProcess function](https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminateprocess) to kill the service instantly.~~
However, if `<stopargument>`/`<stoparguments>` elements are present, winsw will instead launch another process of `<executable>` (or `<stopexecutable>` if that's specified) with the specified arguments, and expects that to initiate the graceful shutdown of the service process.
Winsw will then wait for the two processes to exit on its own, before reporting back to Windows that the service has terminated.
When you use the `<stopargument>`/`<stoparguments>`, you must use `<startargument>`/`<startarguments>` instead of `<argument>`. See the complete example below:
```xml
<executable>catalina.sh</executable>
<startargument>jpda</startargument>
<startargument>run</startargument>
<stopexecutable>catalina.sh</stopexecutable>
<stopargument>stop</stopargument>
```
### stoptimeout
When the service is requested to stop, winsw first attempts to send a Ctrl+C signal,
then wait for up to 15 seconds for the process to exit by itself gracefully.
A process failing to do that (or if the process does not have a console),
then winsw resorts to calling [TerminateProcess function](https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminateprocess) to kill the service instantly.
This optional element allows you to change this "15 seconds" value, so that you can control how long winsw gives the service to shut itself down.
See `<onfailure>` below for how to specify time duration:
```xml
<stoptimeout>10sec</stoptimeout>
```
### Environment
This optional element can be specified multiple times if necessary to specify environment variables to be set for the child process. The syntax is:
```xml
<env name="HOME" value="c:\abc" />
```
### interactive
If this optional element is specified, the service will be allowed to interact with the desktop, such as by showing a new window and dialog boxes.
If your program requires GUI, set this like the following:
```xml
<interactive />
```
Note that since the introduction UAC (Windows Vista and onward), services are no longer really allowed to interact with the desktop.
In those OSes, all that this does is to allow the user to switch to a separate window station to interact with the service.
### beeponshutdown
This optional element is to emit [simple tones](https://docs.microsoft.com/windows/win32/api/utilapiset/nf-utilapiset-beep) when the service shuts down.
This feature should be used only for debugging, as some operating systems and hardware do not support this functionality.
### download
This optional element can be specified multiple times to have the service wrapper retrieve resources from URL and place it locally as a file.
This operation runs when the service is started, before the application specified by `<executable>` is launched.
For servers requiring authentication some parameters must be specified depending on the type of authentication. Only the basic authentication requires additional sub-parameters. Supported authentication types are:
* `none`: default, must not be specified
* `sspi`: Windows [Security Support Provider Interface](https://docs.microsoft.com/windows/win32/secauthn/sspi) including Kerberos, NTLM etc.
* `basic`: Basic authentication, sub-parameters:
* `user="UserName"`
* `password="Passw0rd"`
* `unsecureAuth="true": default="false"`
The parameter `unsecureAuth` is only effective when the transfer protocol is HTTP - unencrypted data transfer. This is a security vulnerability because the credentials are send in clear text! For a SSPI authentication this is not relevant because the authentication tokens are encrypted.
For target servers using the HTTPS transfer protocol it is necessary, that the CA which issued the server certificate is trusted by the client. This is normally the situation when the server ist located in the Internet. When an organisation is using a self issued CA for the intranet this probably is not the case. In this case it is necessary to import the CA to the Certificate MMC of the Windows client. Have a look to the instructions on [Manage Trusted Root Certificates](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc754841(v=ws.11)). The self issued CA must be imported to the Trusted Root Certification Authorities for the computer.
By default, the `download` command does not fail the service startup if the operation fails (e.g. `from` is not available).
In order to force the download failure in such case, it is possible to specify the `failOnError` boolean attribute.
To specify a custom proxy use the parameter `proxy` with the following formats:
- With credentials: `http://USERNAME:PASSWORD@HOST:PORT/`.
- Without credentials: `http://HOST:PORT/`.
Examples:
```xml
<download from="http://example.com/some.dat" to="%BASE%\some.dat" />
<download from="http://example.com/some.dat" to="%BASE%\some.dat" failOnError="true"/>
<download from="http://example.com/some.dat" to="%BASE%\some.dat" proxy="http://192.168.1.5:80/"/>
<download from="https://example.com/some.dat" to="%BASE%\some.dat" auth="sspi" />
<download from="https://example.com/some.dat" to="%BASE%\some.dat" failOnError="true"
auth="basic" user="aUser" password="aPassw0rd" />
<download from="http://example.com/some.dat" to="%BASE%\some.dat"
proxy="http://aUser:aPassw0rd@192.168.1.5:80/"
auth="basic" unsecureAuth="true"
user="aUser" password="aPassw0rd" />
```
This is another useful building block for developing a self-updating service.
Since v2.7, if the destination file exists, WinSW will send its last write time in the `If-Modified-Since` header and skip downloading if `304 Not Modified` is received.
### log
See the "Logging" section above for more details.
### onfailure
This optional repeatable element controls the behaviour when the process launched by winsw fails (i.e., exits with non-zero exit code).
```xml
<onfailure action="restart" delay="10 sec"/>
<onfailure action="restart" delay="20 sec"/>
<onfailure action="reboot" />
```
For example, the above configuration causes the service to restart in 10 seconds after the first failure, restart in 20 seconds after the second failure, then Windows will reboot if the service fails one more time.
Each element contains a mandatory `action` attribute, which controls what Windows SCM will do, and optional `delay` attribute, which controls the delay until the action is taken.
The legal values for action are:
* `restart`: restart the service
* `reboot`: reboot Windows
* `none`: do nothing and leave the service stopped
The possible suffix for the delay attribute is sec/secs/min/mins/hour/hours/day/days. If missing, the delay attribute defaults to 0.
If the service keeps failing and it goes beyond the number of `<onfailure>` configured, the last action will be repeated.
Therefore, if you just want to always restart the service automatically, simply specify one `<onfailure>` element like this:
```xml
<onfailure action="restart" />
```
### resetfailure
This optional element controls the timing in which Windows SCM resets the failure count.
For example, if you specify `<resetfailure>1 hour</resetfailure>` and your service continues to run longer than one hour, then the failure count is reset to zero.
This affects the behaviour of the failure actions (see `<onfailure>` above).
In other words, this is the duration in which you consider the service has been running successfully.
Defaults to 1 day.
### Security descriptor
The security descriptor string for the service in SDDL form.
For more information, see [Security Descriptor Definition Language](https://docs.microsoft.com/windows/win32/secauthz/security-descriptor-definition-language).
```xml
<securtityDescriptor></securtityDescriptor>
```
### Service account
The service is installed as the [LocalSystem account](https://docs.microsoft.com/windows/win32/services/localsystem-account) by default. If your service does not need a high privilege level, consider using the [LocalService account](https://docs.microsoft.com/windows/win32/services/localservice-account), the [NetworkService account](https://docs.microsoft.com/windows/win32/services/networkservice-account) or a user account.
To use a user account, specify a `<serviceaccount>` element like this:
```xml
<serviceaccount>
<domain>YOURDOMAIN</domain>
<user>useraccount</user>
<password>Pa55w0rd</password>
<allowservicelogon>true</allowservicelogon>
</serviceaccount>
```
The `<domain>` is optional and defaults to the local computer.
The `<allowservicelogon>` is optional.
If set to `true`, will automatically set the "Allow Log On As A Service" right to the listed account.
To use [Group Managed Service Accounts](https://docs.microsoft.com/windows-server/security/group-managed-service-accounts/group-managed-service-accounts-overview), append `$` to the account name and remove `<password>` element:
```xml
<serviceaccount>
<domain>YOURDOMAIN</domain>
<user>gmsa_account$</user>
<allowservicelogon>true</allowservicelogon>
</serviceaccount>
```
#### LocalSystem account
To explicitly use the [LocalSystem account](https://docs.microsoft.com/windows/win32/services/localsystem-account), specify the following:
```xml
<serviceaccount>
<user>LocalSystem</user>
</serviceaccount>
```
Note that this account does not have a password, so any password provided is ignored.
#### LocalService account
To use the [LocalService account](https://docs.microsoft.com/windows/win32/services/localservice-account), specify the following:
```xml
<serviceaccount>
<domain>NT AUTHORITY</domain>
<user>LocalService</user>
</serviceaccount>
```
Note that this account does not have a password, so any password provided is ignored.
#### NetworkService account
To use the [NetworkService account](https://docs.microsoft.com/windows/win32/services/networkservice-account), specify the following:
```xml
<serviceaccount>
<domain>NT AUTHORITY</domain>
<user>NetworkService</user>
</serviceaccount>
```
Note that this account does not have a password, so any password provided is ignored.
### Working directory
Some services need to run with a working directory specified.
To do this, specify a `<workingdirectory>` element like this:
```xml
<workingdirectory>C:\application</workingdirectory>
```
### Priority
Optionally specify the scheduling priority of the service process (equivalent of Unix nice)
Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `realtime` (case insensitive.)
```xml
<priority>idle</priority>
```
Specifying a priority higher than normal has unintended consequences.
For more information, see [ProcessPriorityClass Enumeration](https://docs.microsoft.com/dotnet/api/system.diagnostics.processpriorityclass) in .NET docs.
This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage.