DSCResources/DSC_WebSite/en-US/about_WebSite.help.txt
|
.NAME
WebSite .DESCRIPTION The WebSite DSC resource is used to... ## Requirements * Target machine must be running Windows Server 2012 R2 or later. ## Known issues All issues are not listed here, see https://github.com/dsccommunity/WebAdministration/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+WebSite. .PARAMETER Ensure Write - String Allowed values: Present, Absent Ensures that the website is Present or Absent. Defaults to Present. .PARAMETER Name Key - String The desired name of the website. .PARAMETER SiteId Write - UInt32 Optional. The desired IIS site Id for the website. .PARAMETER PhysicalPath Write - String The path to the files that compose the website. .PARAMETER State Write - String Allowed values: Started, Stopped The state of the website. .PARAMETER ApplicationPool Write - String The name of the website???s application pool. .PARAMETER BindingInfo Write - InstanceArray Website's binding information in the form of an array of embedded instances of the DSC_WebBindingInformation CIM class. .PARAMETER DefaultPage Write - StringArray One or more names of files that will be set as Default Documents for this website. .PARAMETER EnabledProtocols Write - String The protocols that are enabled for the website. .PARAMETER ServerAutoStart Write - Boolean When set to $true this will enable Autostart on a Website .PARAMETER AuthenticationInfo Write - Instance Hashtable containing authentication information (Anonymous, Basic, Digest, Windows) .PARAMETER PreloadEnabled Write - Boolean When set to $true this will allow WebSite to automatically start without a request .PARAMETER ServiceAutoStartEnabled Write - Boolean When set to $true this will enable application Autostart (application initalization without an initial request) on a Website .PARAMETER ServiceAutoStartProvider Write - String Adds a AutostartProvider .PARAMETER ApplicationType Write - String Adds a AutostartProvider ApplicationType .PARAMETER LogPath Write - String The directory to be used for logfiles .PARAMETER LogFlags Write - StringArray Allowed values: Date, Time, ClientIP, UserName, SiteName, ComputerName, ServerIP, Method, UriStem, UriQuery, HttpStatus, Win32Status, BytesSent, BytesRecv, TimeTaken, ServerPort, UserAgent, Cookie, Referer, ProtocolVersion, Host, HttpSubStatus The W3C logging fields .PARAMETER LogPeriod Write - String Allowed values: Hourly, Daily, Weekly, Monthly, MaxSize How often the log file should rollover .PARAMETER LogTruncateSize Write - String How large the file should be before it is truncated .PARAMETER LoglocalTimeRollover Write - Boolean Use the localtime for file naming and rollover .PARAMETER LogFormat Write - String Allowed values: IIS, W3C, NCSA Format of the Logfiles. Only W3C supports LogFlags .PARAMETER LogTargetW3C Write - String Allowed values: File, ETW, File,ETW Specifies whether IIS will use Event Tracing or file logging .PARAMETER LogCustomFields Write - InstanceArray Custom logging field information in the form of an array of embedded instances of DSC_LogCustomFieldInformation CIM class .EXAMPLE 1 When specifying a HTTPS web binding you can also specify a certifcate subject, for cases where the certificate is being generated by the same configuration using something like xCertReq. Configuration Sample_WebSite_NewWebsite_UsingCertificateSubject { param ( # Target nodes to apply the configuration [string[]] $NodeName = 'localhost', # Name of the website to create [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $WebSiteName, # Source Path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $SourcePath, # Destination path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $DestinationPath ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = 'Present' Name = 'Web-Asp-Net45' } # Stop the default website WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' PhysicalPath = 'C:\inetpub\wwwroot' DependsOn = '[WindowsFeature]IIS' } # Copy the website content File WebContent { Ensure = 'Present' SourcePath = $SourcePath DestinationPath = $DestinationPath Recurse = $true Type = 'Directory' DependsOn = '[WindowsFeature]AspNet45' } # Create the new Website with HTTPS WebSite NewWebsite { Ensure = 'Present' Name = $WebSiteName State = 'Started' PhysicalPath = $DestinationPath BindingInfo = @( DSC_WebBindingInformation { Protocol = 'HTTPS' Port = 8444 CertificateSubject = 'CN=CertificateSubject' CertificateStoreName = 'My' } ) DependsOn = '[File]WebContent' } } } .EXAMPLE 2 While setting up IIS and stopping the default website is interesting, it isn?t quite useful yet. After all, people typically use IIS to set up websites of their own with custom protocol and bindings. Fortunately, using DSC, adding another website is as simple as using the File and WebSite resources to copy the website content and configure the website. Configuration Sample_WebSite_NewWebsite_UsingCertificateThumbprint { param ( # Target nodes to apply the configuration [string[]] $NodeName = 'localhost', # Name of the website to create [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $WebSiteName, # Source Path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $SourcePath, # Destination path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $DestinationPath ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = 'Present' Name = 'Web-Asp-Net45' } # Stop the default website WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' PhysicalPath = 'C:\inetpub\wwwroot' DependsOn = '[WindowsFeature]IIS' } # Copy the website content File WebContent { Ensure = 'Present' SourcePath = $SourcePath DestinationPath = $DestinationPath Recurse = $true Type = 'Directory' DependsOn = '[WindowsFeature]AspNet45' } # Create the new Website with HTTPS WebSite NewWebsite { Ensure = 'Present' Name = $WebSiteName State = 'Started' PhysicalPath = $DestinationPath BindingInfo = @( DSC_WebBindingInformation { Protocol = 'HTTPS' Port = 8443 CertificateThumbprint = '71AD93562316F21F74606F1096B85D66289ED60F' CertificateStoreName = 'WebHosting' } DSC_WebBindingInformation { Protocol = 'HTTPS' Port = 8444 CertificateThumbprint = 'DEDDD963B28095837F558FE14DA1FDEFB7FA9DA7' CertificateStoreName = 'My' } ) DependsOn = '[File]WebContent' } } } .EXAMPLE 3 configuration Sample_WebSite_NewWebsite { param ( # Target nodes to apply the configuration [String[]] $NodeName = 'localhost', # Name of the website to create [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $WebSiteName, # Optional Site Id for the website [Parameter()] [UInt32] $SiteId, # Source Path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $SourcePath, # Destination path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $DestinationPath ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = 'Present' Name = 'Web-Asp-Net45' } # Stop the default website WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' ServerAutoStart = $false PhysicalPath = 'C:\inetpub\wwwroot' DependsOn = '[WindowsFeature]IIS' } # Copy the website content File WebContent { Ensure = 'Present' SourcePath = $SourcePath DestinationPath = $DestinationPath Recurse = $true Type = 'Directory' DependsOn = '[WindowsFeature]AspNet45' } # Create the new Website WebSite NewWebsite { Ensure = 'Present' Name = $WebSiteName SiteId = $SiteId State = 'Started' ServerAutoStart = $true PhysicalPath = $DestinationPath DependsOn = '[File]WebContent' } } } .EXAMPLE 4 Configuration Sample_WebSite_NewWebsiteFromConfigurationData { # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration # Dynamically find the applicable nodes from configuration data Node $AllNodes.where{ $_.Role -eq 'Web' }.NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = 'Present' Name = 'Web-Asp-Net45' } # Stop an existing website (set up in Sample_WebSite_Default) WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' ServerAutoStart = $false PhysicalPath = $Node.DefaultWebSitePath DependsOn = '[WindowsFeature]IIS' } # Copy the website content File WebContent { Ensure = 'Present' SourcePath = $Node.SourcePath DestinationPath = $Node.DestinationPath Recurse = $true Type = 'Directory' DependsOn = '[WindowsFeature]AspNet45' } # Create a new website WebSite BakeryWebSite { Ensure = 'Present' Name = $Node.WebsiteName State = 'Started' ServerAutoStart = $true PhysicalPath = $Node.DestinationPath DependsOn = '[File]WebContent' } } } # Hashtable to define the environmental data $ConfigurationData = @{ # Node specific data AllNodes = @( # All the WebServers have the following identical information @{ NodeName = '*' WebsiteName = 'FourthCoffee' SourcePath = 'C:\BakeryWebsite\' DestinationPath = 'C:\inetpub\FourthCoffee' DefaultWebSitePath = 'C:\inetpub\wwwroot' }, @{ NodeName = 'WebServer1.fourthcoffee.com' Role = 'Web' }, @{ NodeName = 'WebServer2.fourthcoffee.com' Role = 'Web' } ); } .EXAMPLE 5 configuration Sample_WebSite_RemoveDefault { param ( # Target nodes to apply the configuration [String[]] $NodeName = 'localhost' ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Stop the default website WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' ServerAutoStart = $false PhysicalPath = 'C:\inetpub\wwwroot' DependsOn = '[WindowsFeature]IIS' } } } .EXAMPLE 6 When configuring a new IIS server, several references recommend removing or stopping the default website for security purposes. This example sets up your IIS web server by installing IIS Windows Feature. After that, it will stop the default website by setting `State = Stopped`. Configuration Sample_WebSite_StopDefault { param ( # Target nodes to apply the configuration [string[]]$NodeName = 'localhost' ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = "Present" Name = "Web-Server" } # Stop the default website WebSite DefaultSite { Ensure = "Present" Name = "Default Web Site" State = "Stopped" PhysicalPath = "C:\inetpub\wwwroot" DependsOn = "[WindowsFeature]IIS" } } } .EXAMPLE 7 configuration Sample_WebSite_WithCustomLogFields_EnsureAbsent { param ( # Target nodes to apply the configuration [String[]] $NodeName = 'localhost', # Name of the website to create [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $WebSiteName, # Optional Site Id for the website [Parameter()] [UInt32] $SiteId, # Source Path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $SourcePath, # Destination path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $DestinationPath ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = 'Present' Name = 'Web-Asp-Net45' } # Stop the default website WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' ServerAutoStart = $false PhysicalPath = 'C:\inetpub\wwwroot' DependsOn = '[WindowsFeature]IIS' } # Copy the website content File WebContent { Ensure = 'Present' SourcePath = $SourcePath DestinationPath = $DestinationPath Recurse = $true Type = 'Directory' DependsOn = '[WindowsFeature]AspNet45' } # Create the new Website WebSite NewWebsite { Ensure = 'Present' Name = $WebSiteName SiteId = $SiteId State = 'Started' ServerAutoStart = $true PhysicalPath = $DestinationPath DependsOn = '[File]WebContent' LogFlags = @('Date','Time','ClientIP','ServerIP','UserAgent') LogFormat = 'W3C' LogCustomFields = @( DSC_LogCustomFieldInformation { LogFieldName = 'ClientEncoding' SourceName = 'Accept-Encoding' SourceType = 'RequestHeader' Ensure = 'Absent' } ) } } } .EXAMPLE 8 configuration Sample_WebSite_WithCustomLogFields_EnsurePresentDefault { param ( # Target nodes to apply the configuration [String[]] $NodeName = 'localhost', # Name of the website to create [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $WebSiteName, # Optional Site Id for the website [Parameter()] [UInt32] $SiteId, # Source Path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $SourcePath, # Destination path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $DestinationPath ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = 'Present' Name = 'Web-Asp-Net45' } # Stop the default website WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' ServerAutoStart = $false PhysicalPath = 'C:\inetpub\wwwroot' DependsOn = '[WindowsFeature]IIS' } # Copy the website content File WebContent { Ensure = 'Present' SourcePath = $SourcePath DestinationPath = $DestinationPath Recurse = $true Type = 'Directory' DependsOn = '[WindowsFeature]AspNet45' } # Create the new Website WebSite NewWebsite { Ensure = 'Present' Name = $WebSiteName SiteId = $SiteId State = 'Started' ServerAutoStart = $true PhysicalPath = $DestinationPath DependsOn = '[File]WebContent' LogFlags = @('Date','Time','ClientIP','ServerIP','UserAgent') LogFormat = 'W3C' LogCustomFields = @( DSC_LogCustomFieldInformation { LogFieldName = 'ClientEncoding' SourceName = 'Accept-Encoding' SourceType = 'RequestHeader' } ) } } } .EXAMPLE 9 configuration Sample_WebSite_WithCustomLogFields_EnsurePresentExplicitly { param ( # Target nodes to apply the configuration [String[]] $NodeName = 'localhost', # Name of the website to create [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $WebSiteName, # Optional Site Id for the website [Parameter()] [UInt32] $SiteId, # Source Path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $SourcePath, # Destination path for Website content [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [String] $DestinationPath ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = 'Present' Name = 'Web-Server' } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = 'Present' Name = 'Web-Asp-Net45' } # Stop the default website WebSite DefaultSite { Ensure = 'Present' Name = 'Default Web Site' State = 'Stopped' ServerAutoStart = $false PhysicalPath = 'C:\inetpub\wwwroot' DependsOn = '[WindowsFeature]IIS' } # Copy the website content File WebContent { Ensure = 'Present' SourcePath = $SourcePath DestinationPath = $DestinationPath Recurse = $true Type = 'Directory' DependsOn = '[WindowsFeature]AspNet45' } # Create the new Website WebSite NewWebsite { Ensure = 'Present' Name = $WebSiteName SiteId = $SiteId State = 'Started' ServerAutoStart = $true PhysicalPath = $DestinationPath DependsOn = '[File]WebContent' LogFlags = @('Date','Time','ClientIP','ServerIP','UserAgent') LogFormat = 'W3C' LogCustomFields = @( DSC_LogCustomFieldInformation { LogFieldName = 'ClientEncoding' SourceName = 'Accept-Encoding' SourceType = 'RequestHeader' Ensure = 'Present' } ) } } } .EXAMPLE 10 configuration Sample_WebSite_WithSSLFlags { param ( # Target nodes to apply the configuration [String[]] $NodeName = 'localhost', # Name of the website to create [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [String] $WebSiteName, # Source Path for Website content [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [String] $SourcePath, # Destination path for Website content [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [String] $DestinationPath ) # Import the module that defines custom resources Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration Node $NodeName { # Install the IIS role WindowsFeature IIS { Ensure = "Present" Name = "Web-Server" } # Install the ASP .NET 4.5 role WindowsFeature AspNet45 { Ensure = "Present" Name = "Web-Asp-Net45" } # Stop the default website WebSite DefaultSite { Ensure = "Present" Name = "Default Web Site" State = "Stopped" ServerAutoStart = $false PhysicalPath = "C:\inetpub\wwwroot" DependsOn = "[WindowsFeature]IIS" } # Copy the website content File WebContent { Ensure = "Present" SourcePath = $SourcePath DestinationPath = $DestinationPath Recurse = $true Type = "Directory" DependsOn = "[WindowsFeature]AspNet45" } # Create the new Website # Have it set to the CertificateThumbprint # and set that the Server Name Indication is required WebSite NewWebsite { Ensure = "Present" Name = $WebSiteName State = "Started" PhysicalPath = $DestinationPath DependsOn = "[File]WebContent" BindingInfo = DSC_WebBindingInformation { Protocol = 'https' Port = '443' CertificateStoreName = 'My' CertificateThumbprint = 'BB84DE3EC423DDDE90C08AB3C5A828692089493C' HostName = $WebSiteName IPAddress = '*' SSLFlags = '1' } } } } |