Join AnsibleFest at Red Hat Summit!

microsoft.iis.website module – Configures an IIS website

Note

This module is part of the microsoft.iis collection (version 1.0.2).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install microsoft.iis. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: microsoft.iis.website.

Synopsis

  • Creates, removes, and configures an IIS website.

Requirements

The below requirements are needed on the host that executes this module.

  • IISAdministration PowerShell module

Parameters

Parameter

Comments

application_pool

string

Specifies the application pool in which the website runs.

The application pool must already exist - otherwise the website will not start.

bindings

dictionary

Specifies the website bindings to add, remove or set.

The combination of ip:port:hostname is the binding unique identifier.

The binding ip:port must be available and not used by any other website on the server.

To clear all website bindings, use bindings.set with an empty list.

Default: {}

add

list / elements=dictionary

Specifies a list of bindings to add to the website.

certificate_hash

string

Certificate hash (thumbprint) for the SSL binding. The certificate hash is the unique identifier for the certificate.

You can only provide a certificate thumbprint when bindings.add.protocol=https.

When using the Central Certificate Store feature, the certificate is automatically retrieved from the store rather than manually assigned to the binding.

certificate_store_name

string

Name of the certificate store where the certificate for the binding is located.

Default: "my"

hostname

string

The website binding hostname (DNS).

Mandatory if bindings.add.use_sni=true or bindings.add.use_ccs=true.

ip

string

The website binding listen IP.

port

integer

The website binding listen port.

protocol

string

The website used protocol (http, https).

Choices:

  • "http" ← (default)

  • "https"

use_ccs

boolean

Use Centralized Certificate Store (CCS) for SSL certificates.

Can be used only if bindings.add.protocol=https.

When bindings.add.use_ccs=true, the bindings.add.hostname value must be set.

If true, bindings.add.certificate_hash should not be used.

Choices:

  • false

  • true

use_sni

boolean

Require Server Name Indication (SNI) for SSL certificates.

Can be used only if protocol is https.

When bindings.add.use_sni=true, the bindings.add.hostname value must be set.

Choices:

  • false

  • true

remove

list / elements=dictionary

Specifies a list of bindings to remove from the website.

hostname

string

The website binding hostname (DNS).

ip

string

The website binding listen IP.

port

integer

The website binding listen port.

set

list / elements=dictionary

Specifies the exact list of bindings to set to the website.

This will remove any existing bindings if not in the specified list.

This will add any bindings in the specified list if it does not exist on the website.

Set to an empty list to clear all the website bindings.

certificate_hash

string

Certificate hash (thumbprint) for the SSL binding. The certificate hash is the unique identifier for the certificate.

You can only provide a certificate thumbprint when bindings.set.protocol=https.

When using the Central Certificate Store feature, the certificate is automatically retrieved from the store rather than manually assigned to the binding.

certificate_store_name

string

Name of the certificate store where the certificate for the binding is located.

When using the Central Certificate Store feature, the certificate is automatically retrieved from the store rather than manually assigned to.

Default: "my"

hostname

string

The website binding hostname (DNS).

Mandatory if bindings.set.use_sni=true or bindings.set.use_ccs=true.

ip

string

The website binding listen IP.

port

integer

The website binding listen port.

protocol

string

The website used protocol (http, https).

Choices:

  • "http" ← (default)

  • "https"

use_ccs

boolean

Use Centralized Certificate Store (CCS) for SSL certificates.

Can be used only if bindings.set.protocol=https.

When bindings.set.use_ccs=true, the bindings.set.hostname value must be set.

If true, bindings.set.certificate_hash should not be used.

Choices:

  • false

  • true

use_sni

boolean

Require Server Name Indication (SNI) for SSL certificates.

Can be used only if bindings.set.protocol=https.

When bindings.set.use_sni=true, the bindings.set.hostname value must be set.

Choices:

  • false

  • true

name

string / required

The name of the website to manage.

physical_path

string

Specifies the physical folder path on the remote host to use for the website.

When create a new website physical_path is required.

The specified folder must already exist.

site_id

string

Explicitly set the IIS website numeric ID.

Note that this value cannot be changed after the website has been created.

The site ID must be available and not used by any other website on the server.

state

string

State of the website.

In order to start the website at least one binding should be configured.

Choices:

  • "absent"

  • "started" ← (default)

  • "stopped"

  • "restarted"

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: windows

Target OS/families that can be operated against

See Also

See also

microsoft.iis.website_info

Get information on IIS websites.

microsoft.iis.web_app_pool

Configure IIS Web Application Pools.

Examples

- name: Create a default website in 'Started' state
  microsoft.iis.website:
    name: WebSite
    physical_path: C:\inetpub\wwwroot
    state: started
    bindings:
      set:
        - ip: 127.0.0.1
          port: 80
          hostname: my-website.com

- name: Create a website with two bindings, set all values and start it
  microsoft.iis.website:
    name: WebSite
    site_id: 2
    state: started
    physical_path: C:\wwwroot\websites\my-website
    application_pool: DefaultAppPool
    bindings:
      set:
        - ip: 127.0.0.1
          port: 8081
          hostname: my-website.com
        - ip: 127.0.0.2
          port: 8082
          hostname: my-website.net
          protocol: https
          use_sni: true
          use_ccs: false
          certificate_hash: 5409124040FA1C8FA74939BDA2EF8FD5975BD25B
          certificate_store_name: MY

- name: Remove all the bindings from an existing website
  microsoft.iis.website:
    name: WebSite
    bindings:
      set: []

- name: Remove a specific binding from an existing website
  microsoft.iis.website:
    name: WebSite
    bindings:
      remove:
        - ip: 127.0.0.1
          port: 8081
          hostname: my-website.com

- name: Add bindings to an existing website
  microsoft.iis.website:
    name: WebSite
    bindings:
      add:
        - ip: 127.0.0.3
          port: 8083
          hostname: new-website.com
        - ip: 127.0.0.4
          port: 8084
          hostname: new-website.net

- name: Stop a website
  microsoft.iis.website:
    name: WebSite
    state: stopped

- name: Restart a website (non-idempotent)
  microsoft.iis.website:
    name: WebSite
    state: restarted

- name: Change a website application pool
  microsoft.iis.website:
    name: WebSite
    application_pool: NewAppPool

- name: Change a website physical path
  microsoft.iis.website:
    name: WebSite
    physical_path: C:\wwwroot\websites\my-website

Authors

  • Shahar Golshani (@sgolshan)