Overview

The Wrapper can be used to control a Windows Service with various actions, such as START, STOP, RESUME, QUERY, etc. By default, these actions require Administrator privileges, and a User Account Control approval may be prompted on their execution.

Since version 3.5.42, the Professional Edition of the Wrapper makes it possible to grant permissions on Windows Services. It is possible to configure as many permissions as needed, each of them allowing a user or a group to execute a list of actions on a specific service.

There are a number of cases where it can be useful to change the permissions of a service:

The permissions are either set when installing a service, or when updating an installed service. For the second, the service must be in a stopped state.

Update a service:
.\wrapper.exe -u ../conf/wrapper.conf

This page describes the set of configuration properties used to manage permissions.

The following properties can be listed with incremented indexes:

The following single properties can also be used for advanced configurations:

In addition, it is possible to query the permissions of a service.

Configuring permissions

wrapper.ntservice.permissions.<n>.account

Compatibility :3.5.42
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

Sets the account or the group to which access rights will be granted for the targeted service.

Valid formats are:

  • <local_account_or_group_name>
  • .\<local_account_or_group_name>
  • <domain>\<account_or_group_name>

It is also possible to set the property with 'CURRENT_USER' in order to specify the current user on the machine where the permission will be set. This can be useful when deploying the same configuration to several machines set up with different user names.

There is no default value. This property, along with wrapper.ntservice.permissions.<n>.allow, must be both set for a permission to be valid.

Example:
wrapper.ntservice.permissions.1.account=.\mylocalaccount
wrapper.ntservice.permissions.1.allow=START, STOP

If the account doesn't exist, by default the Wrapper will show an error and stop before setting any permission. However, if a non-existent account is listed in the wrapper.ntservice.permissions.optional_accounts, the permission will just be skipped.

You may configure as many permissions as you want by incrementing the <n> component of the property name (counting up from "1"). By default, the numbering should be in sequence without gaps. The wrapper.ignore_sequence_gaps property can optionally be set to allow gaps in the sequence.

If you have several permissions targeting the same service and the same account, the permissions will be merged using the bitwise OR operator. This means that, for example, if permission #1 grants START, and permission #2 grants STOP, the resulting permission and will grant both START and STOP. This can be used when an include file needs to extend a permission with additional access rights.

NOTE

For safety, the Wrapper doesn't allow to change the permissions of the Administrators group. This could indeed lead to a blocked situation where it is no longer possible to stop/uninstall the service or even reset its permissions.

wrapper.ntservice.permissions.<n>.allow

Compatibility :3.5.42
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

Sets a list of comma-separated actions that a permission grants to a user or a group on a Windows Service.

There is no default value. This property, along with wrapper.ntservice.permissions.<n>.account, must be both set for a permission to be valid. However, you might define it to an empty value or to 'NONE' to remove all permissions for a certain user or group.

The following access rights can be listed:

  • QUERY_STATUS :

    Allows to query the status of the service.

  • QUERY_PERMISSIONS :

    Allows to query the permissions of the service. Use this permission together with UPDATE_CONFIG when updating a service.

  • UPDATE_CONFIG :

    Allows to update the configuration of the service.

  • UPDATE_PERMISSIONS :

    Allows to update permissions of the service.

  • START :

    Allows to start the service.

  • STOP :

    Allows to stop the service.

  • PAUSE_RESUME :

    Allows to pause/continue the service.

  • INTERROGATE :

    Allows to interrogate the service. This permission should be used together with CONTROL_CODE when sending control code to interrogate a service.

  • CONTROL_CODE :

    Allows to send User-Defined Control Commands to the service.

  • ALL :

    All access rights.

  • NONE :

    No access rights.

Example:
wrapper.ntservice.permissions.1.account=CURRENT_USER
wrapper.ntservice.permissions.1.allow=START, STOP, PAUSE_RESUME

If a value that is not listed above is found, it will be skipped and a warning will be printed.

NOTE

Even when permissions are set during the installation of a service, they are actually set after the service is created. Therefore, there are no permissions to install a service, as its installed status is a prerequisite for setting permissions.

wrapper.ntservice.permissions.<n>.service

Compatibility :3.5.42
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

Specifies the name of the service to which the permission should apply.

This property is optional. When it is not specified, the default value will be the name of the current service (the value of wrapper.name).

Example:
wrapper.ntservice.permissions.1.account=CURRENT_USER
wrapper.ntservice.permissions.1.allow=START, STOP, PAUSE_RESUME

wrapper.ntservice.permissions.2.service=dependant_service
wrapper.ntservice.permissions.2.account=CURRENT_USER
wrapper.ntservice.permissions.2.allow=PAUSE_RESUME

A service must exist for the permission to be valid. If the value doesn't match any names of the installed services, by default the Wrapper will show an error and stop before setting any permission. However, if an non-existent service is listed in wrapper.ntservice.permissions.optional_services, the permission will just be skipped.

Optional permissions (for portability)

wrapper.ntservice.permissions.optional_accounts

Compatibility :3.5.42
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

Allows to list optional accounts when setting permissions of a Windows Service. If a permission is set with an account present in this list, and this account doesn't exist on the machine where the Wrapper is executed, the permission will be skipped instead of causing a FATAL error.

Listing optional accounts can be useful when deploying a single configuration file to several machines set up with different accounts. The permissions for which the accounts don't exist will be ignored, leaving the possibility for other permissions to be set normally.

wrapper.ntservice.permissions.optional_services

Compatibility :3.5.42
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

Allows to list optional services when setting permissions of a Windows Service. If a permission is set with a service present in this list, and this service doesn't exist on the machine where the Wrapper is executed, the permission will be skipped instead of causing a FATAL error.

Listing optional services can be useful when deploying a single configuration file to several machines where different services are installed. The permissions for which the services don't exist will be ignored, leaving the possibility for other permissions to be set normally.

Debugging

wrapper.ntservice.permissions.check.loglevel

Compatibility :3.5.42
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

Controls the log level at which debug output are printed when checking permissions.

A permission for an operation that the Wrapper performs on a service is actually composed of several basic access rights provided by the Windows security model. Before executing an operation, the Wrapper will check whether the current user has the permission for it, and thus check that any of the basic access rights are granted. While doing this, a message will be printed to show the status (granted or not) of each access right. This property allows to control the log level of these messages.

The default value is DEBUG.

Example:
Permission check for testwrapper - QUERY_PERMISSIONS (SERVICE_QUERY_STATUS=TRUE, READ_CONTROL=TRUE) -> OK

On the above example, you can see that QUERY_PERMISSIONS is actually composed of SERVICE_QUERY_STATUS and READ_CONTROL. Both base access rights are TRUE, which results in QUERY_PERMISSIONS being granted to the current user.

Query the permissions of a Windows Service

Compatibility :3.5.42
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

It is possible to query the permissions of a service with the following command:

Query the permissions of the current service:
.\wrapper.exe -qp ../conf/wrapper.conf
wrapperm | Current user: mypc\myuser
wrapperm |   Is member of: NT AUTHORITY\INTERACTIVE
wrapperm |
wrapperm | Permissions for the testwrapper service:
wrapperm |
wrapperm |   mypc\myuser:
wrapperm |     START, STOP, PAUSE_RESUME
wrapperm |
wrapperm |   NT AUTHORITY\SYSTEM:
wrapperm |     QUERY_STATUS, QUERY_PERMISSIONS, START, STOP, PAUSE_RESUME, INTERROGATE, CONTROL_CODE
wrapperm |
wrapperm |   NT AUTHORITY\INTERACTIVE:
wrapperm |     QUERY_STATUS, QUERY_PERMISSIONS, INTERROGATE, CONTROL_CODE
wrapperm |
wrapperm |   NT AUTHORITY\SERVICE:
wrapperm |     QUERY_STATUS, QUERY_PERMISSIONS, INTERROGATE, CONTROL_CODE

In the output of the above example, you can see that myuser if a member of NT AUTHORITY\INTERACTIVE and thus inherits its permissions. In addition, START, STOP, PAUSE_RESUME are specifically granted to the user.

You might also want to query the permissions of another service by using '-qp=serviceName'.

Query the permissions of a different service using its name:
.\wrapper.exe -qp=otherservice ../conf/wrapper.conf

Reference - Windows Services

[View/Display]

[Start/Stop]