Task Configuration

Option	Type	Required	Default Value	Description
applicationPool	block list	no	none	Defines one more application pools. See applicationPool schema below for details.
application	block list	yes	none	Defines one more applications. See application schema below for details.
target_website	string	no	none	Specifies an existing target website. In this case the driver will not create a new website but instead use the existing one where it provisions the virtual applications only. Please read the details here.
enable_udp_logging	bool	no	false	Enables a UDP log-sink your application can log to. Please read the details here.
permit_iusr	bool	no	true	Specifies whether you want to permit the IUSR-account on the local directory. When you disable this, you may need to tweak your web.config a bit. Read this for details.
binding	block list	yes	none	Defines one or two port bindings. See binding schema below for details.
service_auto_start_provider	block list	no	none	Registers one or more service auto-start providers in the global IIS applicationHost.config. See service_auto_start_provider schema below for details.
managed_pipeline_mode	string	no	IIS default	Valid options are Integrated or Classic
enable_32bit_app_on_win64	bool	no	IIS default	When true, enables a 32-bit application to run on a computer that runs a 64-bit version of Windows.
managed_runtime_version	string	no	IIS default	Valid options are v4.0, v2.0, None
start_mode	string	no	IIS default	Valid options are OnDemand or AlwaysRunning
idle_timeout	string	no	IIS default	The AppPool idle timeout in the form HH:mm:ss or [00w][00d][00h][00m][00s]
disable_overlapped_recycle	bool	no	IIS default	Defines whether two AppPools are allowed to run while recycling
periodic_restart	string	no	IIS default	The AppPool periodic restart interval in the form HH:mm:ss or [00w][00d][00h][00m][00s]
service_unavailable_response	string	no	IIS default	If this is set to HttpLevel and the app pool isn't running, HTTP.sys will return a 503 http-error. On the other hand if this is set to TcpLevel and the app pool isn't running, HTTP.sys will simply drop the connection. This may be useful when using external load balancers.
queue_length	number	no	IIS default	Indicates to HTTP.sys how many requests to queue for an application pool before rejecting future requests.
start_time_limit	string	no	IIS default	Specifies the time in the form [00w][00d][00h][00m][00s] that IIS waits for an application pool to start. If the application pool does not startup within the startupTimeLimit, the worker process is terminated and the rapid-fail protection count is incremented.
shutdown_time_limit	string	no	IIS default	Specifies the time in the form [00w][00d][00h][00m][00s] that the W3SVC service waits after it initiated a recycle. If the worker process does not shut down within the shutdownTimeLimit, it will be terminated by the W3SVC service.

note

Strikethrough configuration options have been removed in version 0.16.0. Please use the applicationPool block instead.

applicationPool Block

info

In nomad-iis up to version including 0.14.x, all application pool related settings were specified on the root configuration. Starting with version 0.15.0 you need to put these onto a dedicated applicationPool block but you can omit the name if you only need a single app pool. This will be the case most of the time.

Please also read this section for more details about using multiple application pools.

Short Example

config {
  applicationPool {
    managed_runtime_version = "None"
    identity = "NetworkService"
  }
}

Option	Type	Required	Default Value	Description
name	string	no	default	Specifies an alias name for the application pool. This can be used to reference the application pool within the application block. It is limited to 8 characters.
identity	string	no	ApplicationPoolIdentity	Specifies the identity under which the application pool runs. Valid options are ApplicationPoolIdentity, LocalSystem, LocalService, NetworkService, or SpecificUser. Please also see here for details.
username	string	no	none	Specifies the username when identity is set to SpecificUser. This field is required when using SpecificUser identity.
password	string	no	none	Specifies the password for the username when identity is set to SpecificUser. This field is optional and can be omitted for Group Managed Service Accounts (GMSA).
managed_pipeline_mode	string	no	IIS default	Valid options are Integrated or Classic
enable_32bit_app_on_win64	bool	no	IIS default	When true, enables a 32-bit application to run on a computer that runs a 64-bit version of Windows.
managed_runtime_version	string	no	IIS default	Valid options are v4.0, v2.0, None
start_mode	string	no	IIS default	Valid options are OnDemand or AlwaysRunning
idle_timeout	string	no	IIS default	The AppPool idle timeout in the form HH:mm:ss or [00w][00d][00h][00m][00s]
disable_overlapped_recycle	bool	no	IIS default	Defines whether two AppPools are allowed to run while recycling
periodic_restart	string	no	IIS default	The AppPool periodic restart interval in the form HH:mm:ss or [00w][00d][00h][00m][00s]
service_unavailable_response	string	no	IIS default	If this is set to HttpLevel and the app pool isn't running, HTTP.sys will return a 503 http-error. On the other hand if this is set to TcpLevel and the app pool isn't running, HTTP.sys will simply drop the connection. This may be useful when using external load balancers.
queue_length	number	no	IIS default	Indicates to HTTP.sys how many requests to queue for an application pool before rejecting future requests.
start_time_limit	string	no	IIS default	Specifies the time in the form [00w][00d][00h][00m][00s] that IIS waits for an application pool to start. If the application pool does not startup within the startupTimeLimit, the worker process is terminated and the rapid-fail protection count is incremented.
shutdown_time_limit	string	no	IIS default	Specifies the time in the form [00w][00d][00h][00m][00s] that the W3SVC service waits after it initiated a recycle. If the worker process does not shut down within the shutdownTimeLimit, it will be terminated by the W3SVC service.
extension	block list	no	none	Allows for additional attributes for properties not explicitly supported. See extension schema below for details.

warning

Resource statistics (CPU/Memory usage) are currently only collected when the identity is set to ApplicationPoolIdentity.

application Block

Option	Type	Required	Default Value	Description
path	string	yes	none	Defines the path of the web application, containing the application files. If this folder is empty, the Placeholder App will be copied into.
alias	string	no	/	Defines an optional alias at which the application should be hosted below the website. If not set, the application will be hosted at the website level.
application_pool	string	no	default	References an application pool on which this application should be executed.
enable_preload	bool	no	IIS default	Specifies whether the application should be pre-loaded.
service_auto_start_enabled	bool	no	IIS default	Specifies whether the application should be automatically started.
service_auto_start_provider	string	no	IIS default	Specifies the name of the autostart provider if service_auto_start_enabled is set to true. The referenced provider must be registered via a service_auto_start_provider block in the task configuration.
virtual_directory	block list	no	none	Defines optional virtual directories below this application. See virtual_directory schema below for details.
extension	block list	no	none	Allows for additional attributes for properties not explicitly supported. See extension schema below for details.

service_auto_start_provider Block

info

This block registers a service auto-start provider in the global IIS system.applicationHost/serviceAutoStartProviders section of applicationHost.config. This is required when using the service_auto_start_provider option on an application block, as IIS needs to know which managed assembly to load for the named provider.

The driver will automatically add or update the provider registration on task start, and remove it on task stop if no other application on the server still references it.

Option	Type	Required	Default Value	Description
name	string	yes	none	The name of the auto-start provider. This is the value referenced by service_auto_start_provider in the application block.
type	string	yes	none	The fully qualified managed type of the auto-start provider assembly (e.g. MyNamespace.ApplicationPreload, MyAssembly). The class must implement System.Web.Hosting.IProcessHostPreloadClient.

Short Example

config {
  service_auto_start_provider {
    name = "MyPreloadProvider"
    type = "MyNamespace.ApplicationPreload, MyAssembly"
  }

  applicationPool {
    start_mode = "AlwaysRunning"
  }

  application {
    path                        = "local"
    service_auto_start_enabled  = true
    service_auto_start_provider = "MyPreloadProvider"
  }
}

virtual_directory Block

Option	Type	Required	Default Value	Description
alias	string	yes	none	Defines the alias of the virtual directory
path	string	yes	none	Defines the path of the virtual directory
extension	block list	no	none	Allows for additional attributes for properties not explicitly supported. See extension schema below for details.

extension Block

info

In the event that a configurable property is not supported by a block type, an extension may be used. Each extension will set a corresponding attribute via the IIS setting schema. Using an unsupported attribute may cause IIS failures.

Option	Type	Required	Default Value	Description
name	string	yes	none	Defines the attribute name
value	string	yes	none	Defines the attribute value

binding Block

Option	Type	Required	Default Value	Description
type	string	yes	none	Defines the protocol of the port binding. Allowed values are http or https.
port	string	yes	none	Defines the port label of a network block or a static port like "80". Static ports can only be used when hostname is also set. Otherwise use a nomad network-stanza to specify the port.
hostname	string	no	IIS default	Only listens to the specified hostname
require_sni	bool	no	IIS default	Defines whether SNI (Server Name Indication) is required
ip_address	string	no	IIS default	Specifies the IP-Address of the interface to listen on
certificate	block list	no	none	Specifies the certificate to use when using type=https. See certificate schema below for details.

certificate Block

tip

Also refer to this advanced documentation.

Option	Type	Required	Default Value	Description
thumbprint	string	no	none	Specifies the thumbprint (hash) of a local and pre-installed certificate. Make sure the certificate is accessible to IIS by installing it to the My Certificates store on Local Machine.
pfx_file	string	no	none	Specifies the path to a local certificate file. The file must be of type .pfx.
password	string	no	none	Specifies the password for the given pfx-certificate file.
cert_file	string	no	none	Specifies the path to a local certificate file in base64-encoded pem format. When using this option you also need to specify key_file.
key_file	string	no	none	Specifies the path to a local private key file in base64-encoded pkcs8 format. When using this option you also need to specify cert_file.
use_self_signed	bool	no	false	Set this to true if you want to use a self-signed certificate with a validity of one year. Important: This is not intended for production usage and should only be used for short lived tasks like UI- or Integration tests.

Example

note

The following example downloads a very simple HTML app from this repository. Feel free to inspect the ZIP before running the job.

job "static-sample-app" {
  datacenters = ["dc1"]
  type = "service"

  group "app" {
    count = 1

    # See: https://nomad-iis.sevensolutions.cc/docs/tips-and-tricks/in-place-update
    # disconnect {
    #  lost_after = "1m"
    # }

    network {
      port "httplabel" {}
    }

    task "app" {
      driver = "iis"

      artifact {
        source = "https://github.com/sevensolutions/nomad-iis/raw/main/examples/static-sample-app.zip"
        destination = "local"
      }

      config {
        applicationPool {
          identity = "ApplicationPoolIdentity"
        }

        application {
          path = "local"
        }

        binding {
          type = "http"
          port = "httplabel"
        }
      }

      resources {
        cpu    = 100
        memory = 20
      }
    }
  }
}