From 76d82ae4590d99bb812cc36d5750be1b5c07fe78 Mon Sep 17 00:00:00 2001 From: Chris H <53898223+Borgquite@users.noreply.github.com> Date: Tue, 5 Nov 2024 17:08:06 +0000 Subject: [PATCH] WebConfigPropertyCollection: Allow deleting single item property collections, update examples, remove duplicate resource documentation (#644) --- CHANGELOG.md | 5 + README.md | 357 ++---------------- .../DSC_WebConfigPropertyCollection.psm1 | 6 + ...ple_WebConfigPropertyCollection_Remove.ps1 | 1 - ...ConfigPropertyCollection_SingleItemAdd.ps1 | 37 ++ ...figPropertyCollection_SingleItemRemove.ps1 | 36 ++ ...igPropertyCollection.Integration.Tests.ps1 | 60 +++ ...DSC_WebConfigPropertyCollection.config.ps1 | 41 ++ .../DSC_WebConfigPropertyCollection.Tests.ps1 | 24 ++ 9 files changed, 240 insertions(+), 327 deletions(-) create mode 100644 source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemAdd.ps1 create mode 100644 source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemRemove.ps1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e073f97..3eb3436d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md) - WebConfigPropertyCollection - Allowed different property collection key types to be added beyond the default. + - Allowed control over single item property collection key types, including examples - fixes ([issue #379](https://github.com/dsccommunity/WebAdministrationDsc/issues/379)), ([issue #631](https://github.com/dsccommunity/WebAdministrationDsc/issues/631)). ### Changed @@ -24,6 +25,10 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md) - WebAdministrationDsc - Fixed CertificateStoreName default value from `MY` to `My` ([issue #642](https://github.com/dsccommunity/WebAdministrationDsc/issues/642)) +### Removed + +- Removed outdated resources documentation from README.md. + ## [4.2.0] - 2024-08-26 ### Removed diff --git a/README.md b/README.md index 4856cb2f..d3f0e31e 100644 --- a/README.md +++ b/README.md @@ -41,332 +41,6 @@ for some general use scenarios for all of the resources that are in the module. The resource examples are also available in the [WebAdministration Wiki](https://github.com/dsccommunity/WebAdministrationDsc/wiki). -## Installation - -### From GitHub source code - -To manually install the module, download the source code from GitHub and unzip -the contents to the '$env:ProgramFiles\WindowsPowerShell\Modules' folder. - -### From PowerShell Gallery - -To install from the PowerShell gallery using PowerShellGet (in PowerShell 5.0) -run the following command: - -```powershell -Find-Module -Name WebAdministrationDsc | Install-Module -``` - -To confirm installation, run the below command and ensure you see the -DSC resources available: - -```powershell -Get-DscResource -Module WebAdministrationDsc -``` - -## Requirements - -The minimum Windows Management Framework (PowerShell) version required is -4.0 or higher. - ->Note: In the CI pipeline the resource are only tested on PowerShell 5.1, ->so PowerShell 4.0 support is best effort as this time. - -## Examples - -You can review the [Examples](/source/Examples) directory in the WebAdministrationDsc -module for some general use scenarios for all of the resources that are in -the module. - -## Resources - -* [WebApplicationHandler](#webapplicationhandler) -* [IisFeatureDelegation](#iisfeaturedelegation) -* [IISLogging](#iislogging) -* [IisMimeTypeMapping](#iismimetypemapping) -* [IisModule](#IisModule) -* [SslSettings](#sslsettings) -* [WebApplication](#webapplication) -* [WebAppPool](#webapppool) -* [WebAppPoolDefaults](#webapppooldefaults) -* [WebConfigProperty](#webconfigproperty) -* [WebConfigPropertyCollection](#webconfigpropertycollection) -* [WebSite](#website) -* [WebSiteDefaults](#websitedefaults) -* [WebVirtualDirectory](#webvirtualdirectory) - -### WebApplicationHandler - -* **[String] Ensure** _(Write)_: Indicates if the application handler exists. Set this property to `Absent` to ensure that the application handler does not exist. Default value is 'Present'. -{ *Present* | Absent } -* **[String] Name** _(Key)_: Specifies the name of the new request handler. -* **[String] Location** _(Write)_: Specifies The location of the configuration setting. Location tags are frequently used for configuration settings that must be set more precisely than per application or per virtual directory. -* **[String] PhysicalHandlerPath** _(Write)_: Specifies the physical path to the handler. This parameter applies to native modules only. -* **[String] Verb** _(Write)_: Specifies the HTTP verbs that are handled by the new handler. -* **[String] Modules** _(Write)_: Specifies the modules used for the handler. -* **[String[]] Path** _(Required)_: Specifies an IIS configuration path. -* **[String] PreCondition** _(Write)_: Specifies preconditions for the new handler. -* **[String] RequiredAccess** _(Write)_: Specifies the user rights that are required for the new handler. { None | Read | Write | Script | Execute } -* **[String] ScriptProcessor** _(Write)_: Specifies the script processor that runs for the module. -* **[String] Type** _(Write)_: Specifies the managed type of the new module. This parameter applies to managed modules only. -* **[String] ResourceType** _(Write)_: Specifies the resource type this handler runs. See [ResourceType](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/handlers/add). -* **[Boolean] AllowPathInfo** _(Write)_: Specifies whether the handler processes full path information in a URI, such as contoso/marketing/imageGallery.aspx. If the value is true, the -handler processes the full path, contoso/marketing/imageGallery. If the value is false, the handler processes only the last section of the path, /imageGallery. -* **[UInt64] ResponseBufferLimit** _(Write)_: Specifies the maximum size, in bytes, of the response buffer for a request handler runs. - -### IisFeatureDelegation - -This resource manages the IIS configuration section locking (overrideMode) to control what configuration can be set in web.config. - -* **Filter**: Specifies the IIS configuration section to lock or unlock in this format: **/system.webserver/security/authentication/anonymousAuthentication** -* **OverrideMode**: Mode of that section { **Allow** | **Deny** } -* **Path**: Specifies the configuration path. This can be either an IIS configuration path in the format computer machine/webroot/apphost, or the IIS module path in this format IIS:\sites\Default Web Site. *WARNING: both path types can be used to manage the same feature delegation, however, there is no way to control if two resources in the configuration set the same feature delegation*. - -### IISLogging - -**Note** This will set the logfile settings for **all** websites; for individual websites use the Log options under **WebSite** - -* **LogPath**: The directory to be used for logfiles. -* **LogFlags**: The W3C logging fields: The values that are allowed for this property are: `Date`,`Time`,`ClientIP`,`UserName`,`SiteName`,`ComputerName`,`ServerIP`,`Method`,`UriStem`,`UriQuery`,`HttpStatus`,`Win32Status`,`BytesSent`,`BytesRecv`,`TimeTaken`,`ServerPort`,`UserAgent`,`Cookie`,`Referer`,`ProtocolVersion`,`Host`,`HttpSubStatus` -* **LogPeriod**: How often the log file should rollover. The values that are allowed for this property are: `Hourly`,`Daily`,`Weekly`,`Monthly`,`MaxSize` -* **LogTruncateSize**: How large the file should be before it is truncated. If this is set then LogPeriod will be ignored if passed in and set to MaxSize. The value must be a valid integer between `1048576 (1MB)` and `4294967295 (4GB)`. -* **LoglocalTimeRollover**: Use the localtime for file naming and rollover. The acceptable values for this property are: `$true`, `$false` -* **LogFormat**: Format of the Logfiles. **Note**Only W3C supports LogFlags. The acceptable values for this property are: `IIS`,`W3C`,`NCSA` -* **LogTargetW3C**: Log Target of the W3C Logfiles. The acceptable values for this property are: `File`,`ETW`,`File,ETW` -* **LogCustomFields**: Custom logging field information the form of an array of embedded instances of the **DSC_LogCustomField** CIM class that implements the following properties: - * **LogFieldName**: Field name to identify the custom field within the log file. Please note that the field name cannot contain spaces. - * **SourceType**: You can select `RequestHeader`, `ResponseHeader`, or `ServerVariable` (note that enhanced logging cannot log a server variable with a name that contains lower-case characters - to include a server variable in the event log just make sure that its name consists of all upper-case characters). - * **SourceName**: Name of the HTTP header or server variable (depending on the Source Type you selected) that contains a value that you want to log. - -### IisMimeTypeMapping - -* **ConfigurationPath**: This can be either an IIS configuration path in the format computername/webroot/apphost, or the IIS module path in this format IIS:\sites\Default Web Site. -* **Extension**: The file extension to map such as **.html** or **.xml** -* **MimeType**: The MIME type to map that extension to such as **text/html** -* **Ensure**: Ensures that the MIME type mapping is **Present** or **Absent**. Defaults to **Present**. - -### IisModule - -* **Path**: The path to the module to be registered. -* **Name**: The logical name to register the module as in IIS. -* **RequestPath**: The allowed request paths, such as *.php -* **Verb**: An array of allowed verbs, such as get and post. -* **SiteName**: The name of the Site to register the module for. If empty, the resource will register the module with all of IIS. -* **ModuleType**: The type of the module. Currently, only FastCgiModule is supported. -* **Ensure**: Ensures that the module is **Present** or **Absent**. Defaults to **Present**. - -### SslSettings - -* **Name**: The Name of website in which to modify the SSL Settings -* **Bindings**: The SSL bindings to implement. -* **Ensure**: Ensures if the bindings are **Present** or **Absent**. Defaults to **Present**. - -### WebApplication - -* **Website**: Name of website with which the web application is associated. -* **Name**: The desired name of the web application. -* **WebAppPool**: Web application’s application pool. -* **PhysicalPath**: The path to the files that compose the web application. -* **Ensure**: Ensures that the web application is **Present** or **Absent**. Defaults to **Present**. -* **PreloadEnabled**: When set to `$true` this will allow WebSite to automatically start without a request -* **ServiceAutoStartEnabled**: When set to `$true` this will enable Autostart on a Website -* **ServiceAutoStartProvider**: Adds a AutostartProvider -* **ApplicationType**: Adds a AutostartProvider ApplicationType -* **AuthenticationInfo**: Web Application's authentication information in the form of an array of embedded instances of the **DSC_WebApplicationAuthenticationInformation** CIM class. **DSC_WebApplicationAuthenticationInformation** take the following properties: - * **Anonymous**: The acceptable values for this property are: `$true`, `$false` - * **Basic**: The acceptable values for this property are: `$true`, `$false` - * **Digest**: The acceptable values for this property are: `$true`, `$false` - * **Windows**: The acceptable values for this property are: `$true`, `$false` -* **SslFlags**: SslFlags for the application: The acceptable values for this property are: `''`, `Ssl`, `SslNegotiateCert`, `SslRequireCert`, `Ssl128` -* **EnabledProtocols**: EnabledProtocols for the application. The acceptable values for this property are: `http`, `https`, `net.tcp`, `net.msmq`, `net.pipe` - -### WebAppPool - -* **Name** : Indicates the application pool name. The value must contain between `1` and `64` characters. -* **Ensure** : Indicates if the application pool exists. Set this property to `Absent` to ensure that the application pool does not exist. - Setting it to `Present` (the default value) ensures that the application pool exists. -* **State** : Indicates the state of the application pool. The values that are allowed for this property are: `Started`, `Stopped`. -* **autoStart** : When set to `$true`, indicates to the World Wide Web Publishing Service (W3SVC) that the application pool should be automatically started when it is created or when IIS is started. -* **CLRConfigFile** : Indicates the .NET configuration file for the application pool. -* **enable32BitAppOnWin64** : When set to `$true`, enables a 32-bit application to run on a computer that runs a 64-bit version of Windows. -* **enableConfigurationOverride** : When set to `$true`, indicates that delegated settings in Web.config files will be processed for applications within this application pool. - When set to `$false`, all settings in Web.config files will be ignored for this application pool. -* **managedPipelineMode** : Indicates the request-processing mode that is used to process requests for managed content. The values that are allowed for this property are: `Integrated`, `Classic`. -* **managedRuntimeLoader** : Indicates the managed loader to use for pre-loading the application pool. -* **managedRuntimeVersion** : Indicates the CLR version to be used by the application pool. The values that are allowed for this property are: `v4.0`, `v2.0`, and `""`. -* **passAnonymousToken** : When set to `$true`, the Windows Process Activation Service (WAS) creates and passes a token for the built-in IUSR anonymous user account to the Anonymous authentication module. - The Anonymous authentication module uses the token to impersonate the built-in account. When this property is set to `$false`, the token will not be passed. -* **startMode** : Indicates the startup type for the application pool. The values that are allowed for this property are: `OnDemand`, `AlwaysRunning`. -* **queueLength** : Indicates the maximum number of requests that HTTP.sys will queue for the application pool. The value must be a valid integer between `10` and `65535`. -* **cpuAction** : Configures the action that IIS takes when a worker process exceeds its configured CPU limit. - The values that are allowed for this property are: `NoAction`, `KillW3wp`, `Throttle`, and `ThrottleUnderLoad`. -* **cpuLimit** : Configures the maximum percentage of CPU time (in 1/1000ths of one percent) that the worker processes in the application pool are allowed to consume over a period of time as indicated by the **cpuResetInterval** property. - The value must be a valid integer between `0` and `100000`. -* **cpuResetInterval** : Indicates the reset period (in minutes) for CPU monitoring and throttling limits on the application pool. - The value must be a string representation of a TimeSpan value. The valid range (in minutes) is `0` to `1440`. - Setting the value of this property to `00:00:00` disables CPU monitoring. -* **cpuSmpAffinitized** : Indicates whether a particular worker process assigned to the application pool should also be assigned to a given CPU. -* **cpuSmpProcessorAffinityMask** : Indicates the hexadecimal processor mask for multi-processor computers, which indicates to which CPU the worker processes in the application pool should be bound. - Before this property takes effect, the **cpuSmpAffinitized** property must be set to `$true` for the application pool. - The value must be a valid integer between `0` and `4294967295`. -* **cpuSmpProcessorAffinityMask2** : Indicates the high-order DWORD hexadecimal processor mask for 64-bit multi-processor computers, which indicates to which CPU the worker processes in the application pool should be bound. - Before this property takes effect, the **cpuSmpAffinitized** property must be set to `$true` for the application pool. - The value must be a valid integer between `0` and `4294967295`. -* **identityType** : Indicates the account identity under which the application pool runs. - The values that are allowed for this property are: `ApplicationPoolIdentity`, `LocalService`, `LocalSystem`, `NetworkService`, and `SpecificUser`. -* **Credential** : Indicates the custom account crededentials. This property is only valid when the **identityType** property is set to `SpecificUser`. -* **idleTimeout** : Indicates the amount of time (in minutes) a worker process will remain idle before it shuts down. - The value must be a string representation of a TimeSpan value and must be less than the **restartTimeLimit** property value. The valid range (in minutes) is `0` to `43200`. -* **idleTimeoutAction** : Indicates the action to perform when the idle timeout duration has been reached. - The values that are allowed for this property are: `Terminate`, `Suspend`. -* **loadUserProfile** : Indicates whether IIS loads the user profile for the application pool identity. -* **logEventOnProcessModel** : Indicates that IIS should generate an event log entry for each occurrence of the specified process model events. -* **logonType** : Indicates the logon type for the process identity. The values that are allowed for this property are: `LogonBatch`, `LogonService`. -* **manualGroupMembership** : Indicates whether the IIS_IUSRS group Security Identifier (SID) is added to the worker process token. -* **maxProcesses** : Indicates the maximum number of worker processes that would be used for the application pool. - The value must be a valid integer between `0` and `2147483647`. -* **pingingEnabled** : Indicates whether pinging (health monitoring) is enabled for the worker process(es) serving this application pool. -* **pingInterval** : Indicates the period of time (in seconds) between health monitoring pings sent to the worker process(es) serving this application pool. - The value must be a string representation of a TimeSpan value. The valid range (in seconds) is `1` to `4294967`. -* **pingResponseTime** : Indicates the maximum time (in seconds) that a worker process is given to respond to a health monitoring ping. - The value must be a string representation of a TimeSpan value. The valid range (in seconds) is `1` to `4294967`. -* **setProfileEnvironment** : Indicates the environment to be set based on the user profile for the new process. -* **shutdownTimeLimit** : Indicates the period of time (in seconds) a worker process is given to finish processing requests and shut down. - The value must be a string representation of a TimeSpan value. The valid range (in seconds) is `1` to `4294967`. -* **startupTimeLimit** : Indicates the period of time (in seconds) a worker process is given to start up and initialize. - The value must be a string representation of a TimeSpan value. The valid range (in seconds) is `1` to `4294967`. -* **orphanActionExe** : Indicates an executable to run when a worker process is orphaned. -* **orphanActionParams** : Indicates parameters for the executable that is specified in the **orphanActionExe** property. -* **orphanWorkerProcess** : Indicates whether to assign a worker process to an orphan state instead of terminating it when the application pool fails. - If `$true`, an unresponsive worker process will be orphaned instead of terminated. -* **loadBalancerCapabilities** : Indicates the response behavior of a service when it is unavailable. The values that are allowed for this property are: `HttpLevel`, `TcpLevel`. - If set to `HttpLevel` and the application pool is stopped, HTTP.sys will return HTTP 503 error. If set to `TcpLevel`, HTTP.sys will reset the connection. -* **rapidFailProtection** : Indicates whether rapid-fail protection is enabled. - If `$true`, the application pool is shut down if there are a specified number of worker process crashes within a specified time period. -* **rapidFailProtectionInterval** : Indicates the time interval (in minutes) during which the specified number of worker process crashes must occur before the application pool is shut down by rapid-fail protection. - The value must be a string representation of a TimeSpan value. The valid range (in minutes) is `1` to `144000`. -* **rapidFailProtectionMaxCrashes** : Indicates the maximum number of worker process crashes permitted before the application pool is shut down by rapid-fail protection. - The value must be a valid integer between `0` and `2147483647`. -* **autoShutdownExe** : Indicates an executable to run when the application pool is shut down by rapid-fail protection. -* **autoShutdownParams** : Indicates parameters for the executable that is specified in the **autoShutdownExe** property. -* **disallowOverlappingRotation** : Indicates whether the W3SVC service should start another worker process to replace the existing worker process while that process is shutting down. - If `$true`, the application pool recycle will happen such that the existing worker process exits before another worker process is created. -* **disallowRotationOnConfigChange** : Indicates whether the W3SVC service should rotate worker processes in the application pool when the configuration has changed. - If `$true`, the application pool will not recycle when its configuration is changed. -* **logEventOnRecycle** : Indicates that IIS should generate an event log entry for each occurrence of the specified recycling events. -* **restartMemoryLimit** : Indicates the maximum amount of virtual memory (in KB) a worker process can consume before causing the application pool to recycle. - The value must be a valid integer between `0` and `4294967295`. - A value of `0` means there is no limit. -* **restartPrivateMemoryLimit** : Indicates the maximum amount of private memory (in KB) a worker process can consume before causing the application pool to recycle. - The value must be a valid integer between `0` and `4294967295`. - A value of `0` means there is no limit. -* **restartRequestsLimit** : Indicates the maximum number of requests the application pool can process before it is recycled. - The value must be a valid integer between `0` and `4294967295`. - A value of `0` means the application pool can process an unlimited number of requests. -* **restartTimeLimit** : Indicates the period of time (in minutes) after which the application pool will recycle. - The value must be a string representation of a TimeSpan value. The valid range (in minutes) is `0` to `432000`. - A value of `00:00:00` means the application pool does not recycle on a regular interval. -* **restartSchedule** : Indicates a set of specific local times, in 24 hour format, when the application pool is recycled. - The value must be an array of string representations of TimeSpan values. - TimeSpan values must be between `00:00:00` and `23:59:59` seconds inclusive, with a granularity of 60 seconds. - Setting the value of this property to `""` disables the schedule. - -### WebAppPoolDefaults - -* **IsSingleInstance**: Specifies the resource is a single instance, the value must be **Yes** -* **ManagedRuntimeVersion**: CLR Version {v2.0|v4.0|} empty string for unmanaged. -* **ApplicationPoolIdentity**: {ApplicationPoolIdentity | LocalService | LocalSystem | NetworkService} - -### WebConfigProperty - -Ensures the value of an identified property in the web.config file. - -* **WebsitePath**: Path to website location (IIS or WebAdministration format). -* **Filter**: Filter used to locate property to update. -* **PropertyName**: Name of the property to update. -* **Value**: Value of the property to update. -* **Ensure**: Indicates if the property and value should be present or absent. Defaults to 'Present'. { *Present* | Absent } - -### WebConfigPropertyCollection - -Ensures the value of an identified property collection item's property in the web.config file. Builds upon the **WebConfigKeyValue** resource to support all web.config elements that contain collections of child items. - -* **WebsitePath**: Path to website location (IIS or WebAdministration format). -* **Filter**: Filter used to locate property collection to update. -* **CollectionName**: Name of the property collection to update. -* **ItemName**: Name of the property collection item to update. -* **ItemKeyName**: Name of the key of the property collection item to update. -* **ItemKeyValue**: Value of the key of the property collection item to update. -* **ItemPropertyName**: Name of the property of the property collection item to update. -* **ItemPropertyValue**: Value of the property of the property collection item to update. -* **Ensure**: Indicates if the property and value should be present or absent. Defaults to 'Present'. { *Present* | Absent } - -### WebSite - -* **Name** : The desired name of the website. -* **SiteId** : Optional. The desired IIS site Id for the website. -* **PhysicalPath**: The path to the files that compose the website. -* **State**: The state of the website: { Started | Stopped } -* **BindingInfo**: Website's binding information in the form of an array of embedded instances of the **DSC_WebBindingInformation** CIM class that implements the following properties: - * **Protocol**: The protocol of the binding. This property is required. The acceptable values for this property are: `http`, `https`, `msmq.formatname`, `net.msmq`, `net.pipe`, `net.tcp`. - * **BindingInformation**: The binding information in the form a colon-delimited string that includes the IP address, port, and host name of the binding. This property is ignored for `http` and `https` bindings if at least one of the following properties is specified: **IPAddress**, **Port**, **HostName**. - * **IPAddress**: The IP address of the binding. This property is only applicable for `http` and `https` bindings. The default value is `*`. - * **Port**: The port of the binding. The value must be a positive integer between `1` and `65535`. This property is only applicable for `http` (the default value is `80`) and `https` (the default value is `443`) bindings. - * **HostName**: The host name of the binding. This property is only applicable for `http` and `https` bindings. - * **CertificateThumbprint**: The thumbprint of the certificate. This property is only applicable for `https` bindings. - * **CertificateSubject**: The subject of the certificate if the thumbprint isn't known. This property is only applicable for `https` bindings. - * **CertificateStoreName**: The name of the certificate store where the certificate is located. This property is only applicable for `https` bindings. The acceptable values for this property are: `My`, `WebHosting`. The default value is `My`. - * **SslFlags**: The type of binding used for Secure Sockets Layer (SSL) certificates. This property is supported in IIS 8.0 or later, and is only applicable for `https` bindings. The acceptable values for this property are: - * **0**: The default value. The secure connection be made using an IP/Port combination. Only one certificate can be bound to a combination of IP address and the port. - * **1**: The secure connection be made using the port number and the host name obtained by using Server Name Indication (SNI). It allows multiple secure websites with different certificates to use the same IP address. - * **2**: The secure connection be made using the Centralized Certificate Store without requiring a Server Name Indication. - * **3**: The secure connection be made using the Centralized Certificate Store while requiring Server Name Indication. -* **ApplicationPool**: The name of the website’s application pool. -* **DefaultPage**: One or more names of files that will be set as Default Documents for this website. -* **EnabledProtocols**: The protocols that are enabled for the website. -* **ServerAutoStart**: When set to `$true` this will enable Autostart on a Website -* **Ensure**: Ensures that the website is **Present** or **Absent**. Defaults to **Present**. -* **PreloadEnabled**: When set to `$true` this will allow WebSite to automatically start without a request -* **ServiceAutoStartEnabled**: When set to `$true` this will enable application Autostart (application initalization without an initial request) on a Website -* **ServiceAutoStartProvider**: Adds a AutostartProvider -* **ApplicationType**: Adds a AutostartProvider ApplicationType -* **AuthenticationInfo**: Website's authentication information in the form of an embedded instance of the **DSC_WebAuthenticationInformation** CIM class. -**DSC_WebAuthenticationInformation** takes the following properties: - * **Anonymous**: The acceptable values for this property are: `$true`, `$false` - * **Basic**: The acceptable values for this property are: `$true`, `$false` - * **Digest**: The acceptable values for this property are: `$true`, `$false` - * **Windows**: The acceptable values for this property are: `$true`, `$false` -* **LogPath**: The directory to be used for logfiles. -* **LogFlags**: The W3C logging fields: The values that are allowed for this property are: `Date`,`Time`,`ClientIP`,`UserName`,`SiteName`,`ComputerName`,`ServerIP`,`Method`,`UriStem`,`UriQuery`,`HttpStatus`,`Win32Status`,`BytesSent`,`BytesRecv`,`TimeTaken`,`ServerPort`,`UserAgent`,`Cookie`,`Referer`,`ProtocolVersion`,`Host`,`HttpSubStatus` -* **LogPeriod**: How often the log file should rollover. The values that are allowed for this property are: `Hourly`,`Daily`,`Weekly`,`Monthly`,`MaxSize` -* **LogTargetW3C**: Log Target of the W3C Logfiles. The acceptable values for this property are: `File`,`ETW`,`File,ETW` -* **LogTruncateSize**: How large the file should be before it is truncated. If this is set then LogPeriod will be ignored if passed in and set to MaxSize. The value must be a valid integer between `1048576 (1MB)` and `4294967295 (4GB)`. -* **LoglocalTimeRollover**: Use the localtime for file naming and rollover. The acceptable values for this property are: `$true`, `$false` -* **LogFormat**: Format of the Logfiles. **Note**Only W3C supports LogFlags. The acceptable values for this property are: `IIS`,`W3C`,`NCSA` -* **LogCustomFields**: Custom logging field information the form of an array of embedded instances of the **DSC_LogCustomFieldInformation** CIM class that implements the following properties: - * **LogFieldName**: Field name to identify the custom field within the log file. Please note that the field name cannot contain spaces. - * **SourceType**: The acceptable values for this property are: `RequestHeader`, `ResponseHeader`, or `ServerVariable` (note that enhanced logging cannot log a server variable with a name that contains lower-case characters - to include a server variable in the event log just make sure that its name consists of all upper-case characters). - * **SourceName**: Name of the HTTP header or server variable (depending on the Source Type you selected) that contains a value that you want to log. - -### WebSiteDefaults - -* **Key**: Required Key value, always **Machine** -* **LogFormat**: Format of the Logfiles. **Note**Only W3C supports LogFlags. The acceptable values for this property are: `IIS`,`W3C`,`NCSA`,`Custom`. -* **LogDirectory**: Directory for IIS logs. -* **TraceLogDirectory**: Directory for FREB (Failed Request Tracing) logs. -* **DefaultApplicationPool**: Name of the default application pool used by websites. -* **AllowSubDirConfig**: Should IIS look for config files in subdirectories, either **true** or **false** - -### WebVirtualDirectory - -* **Website**: Name of website with which virtual directory is associated -* **WebApplication**: The name of the containing web application or an empty string for the containing website -* **PhysicalPath**: The path to the files that compose the virtual directory -* **Name**: The name of the virtual directory -* **Ensure**: Ensures if the virtual directory is **Present** or **Absent**. Defaults to **Present**. - -## Examples - ### Registering PHP When configuring an IIS Application that uses PHP, you first need to register the PHP CGI module with IIS. @@ -507,3 +181,34 @@ xPhp -PackageFolder "C:\packages" ` -ConfigurationPath "C:\MyPhp.ini" ` -installMySqlExt $false ``` + +## Installation + +### From GitHub source code + +To manually install the module, download the source code from GitHub and unzip +the contents to the '$env:ProgramFiles\WindowsPowerShell\Modules' folder. + +### From PowerShell Gallery + +To install from the PowerShell gallery using PowerShellGet (in PowerShell 5.0) +run the following command: + +```powershell +Find-Module -Name WebAdministrationDsc | Install-Module +``` + +To confirm installation, run the below command and ensure you see the +DSC resources available: + +```powershell +Get-DscResource -Module WebAdministrationDsc +``` + +## Requirements + +The minimum Windows Management Framework (PowerShell) version required is +4.0 or higher. + +>Note: In the CI pipeline the resource are only tested on PowerShell 5.1, +>so PowerShell 4.0 support is best effort as this time. diff --git a/source/DSCResources/DSC_WebConfigPropertyCollection/DSC_WebConfigPropertyCollection.psm1 b/source/DSCResources/DSC_WebConfigPropertyCollection/DSC_WebConfigPropertyCollection.psm1 index 062e6eeb..58c1dc33 100644 --- a/source/DSCResources/DSC_WebConfigPropertyCollection/DSC_WebConfigPropertyCollection.psm1 +++ b/source/DSCResources/DSC_WebConfigPropertyCollection/DSC_WebConfigPropertyCollection.psm1 @@ -274,6 +274,12 @@ function Set-TargetResource Write-Verbose ` -Message ($script:localizedData.VerboseSetTargetRemoveItem -f $ItemPropertyName ) + # If we are removing a single collection item with the wildcard syntax for the key, set key name to match the property name + if ($ItemKeyName -eq '*') + { + $ItemKeyName = $ItemPropertyName + } + $filter = "$($Filter)/$($CollectionName)" Remove-WebConfigurationProperty ` -PSPath $WebsitePath ` diff --git a/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_Remove.ps1 b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_Remove.ps1 index 25d513d2..5ab7441e 100644 --- a/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_Remove.ps1 +++ b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_Remove.ps1 @@ -30,7 +30,6 @@ Configuration Sample_WebConfigPropertyCollection_Remove ItemKeyName = 'verb' ItemKeyValue = 'TRACE' ItemPropertyName = 'allowed' - ItemPropertyValue = 'false' Ensure = 'Absent' } } diff --git a/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemAdd.ps1 b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemAdd.ps1 new file mode 100644 index 00000000..3265deee --- /dev/null +++ b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemAdd.ps1 @@ -0,0 +1,37 @@ +<# +.SYNOPSIS + Make appsettings.json inaccessible to clients. + +.DESCRIPTION + This example shows how to use the WebConfigPropertyCollection DSC resource for adding a single item configuration element. + It will add an "add" element to the system.webServer/security/requestFiltering/hiddenSegments collection to block appsettings.json. +#> +Configuration Sample_WebConfigPropertyCollection_SingleItemAdd +{ + param + ( + # Target nodes to apply the configuration. + [Parameter()] + [String[]] + $NodeName = 'localhost' + ) + + # Import the modules that define custom resources + Import-DscResource -ModuleName WebAdministrationDsc + + Node $NodeName + { + WebConfigPropertyCollection "$($NodeName) - Block appsettings.json" + { + WebsitePath = 'MACHINE/WEBROOT/APPHOST' + Filter = 'system.webServer/security/requestFiltering' + CollectionName = 'hiddenSegments' + ItemName = 'add' + ItemKeyName = '*' + ItemKeyValue = 'appsettings.json' + ItemPropertyName = 'segment' + ItemPropertyValue = 'appsettings.json' + Ensure = 'Present' + } + } +} diff --git a/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemRemove.ps1 b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemRemove.ps1 new file mode 100644 index 00000000..430c97e2 --- /dev/null +++ b/source/Examples/Resources/WebConfigPropertyCollection/Sample_WebConfigPropertyCollection_SingleItemRemove.ps1 @@ -0,0 +1,36 @@ +<# +.SYNOPSIS + Removes making appsettings.json inaccessible to clients. + +.DESCRIPTION + This example shows how to use the WebConfigPropertyCollection DSC resource for removing a single item configuration element. + It will remove the "add" element from the system.webServer/security/requestFiltering/hiddenSegments collection (if present) for blocking appsettings.json. +#> +Configuration Sample_WebConfigPropertyCollection_SingleItemRemove +{ + param + ( + # Target nodes to apply the configuration. + [Parameter()] + [String[]] + $NodeName = 'localhost' + ) + + # Import the modules that define custom resources + Import-DscResource -ModuleName WebAdministrationDsc + + Node $NodeName + { + WebConfigPropertyCollection "$($NodeName) - Remove blocking appsettings.json" + { + WebsitePath = 'MACHINE/WEBROOT/APPHOST' + Filter = 'system.webServer/security/requestFiltering' + CollectionName = 'hiddenSegments' + ItemName = 'add' + ItemKeyName = '*' + ItemKeyValue = 'appsettings.json' + ItemPropertyName = 'segment' + Ensure = 'Absent' + } + } +} diff --git a/tests/Integration/DSC_WebConfigPropertyCollection.Integration.Tests.ps1 b/tests/Integration/DSC_WebConfigPropertyCollection.Integration.Tests.ps1 index d5a3dd3b..7ab93555 100644 --- a/tests/Integration/DSC_WebConfigPropertyCollection.Integration.Tests.ps1 +++ b/tests/Integration/DSC_WebConfigPropertyCollection.Integration.Tests.ps1 @@ -59,6 +59,12 @@ try IntegerItemKeyValue = 'Content-Type' IntegerItemPropertyName = 'Sizelimit' IntegerItemPropertyValue = [string](Get-Random -Minimum 11 -Maximum 100) + SingleItemFilter = 'system.webServer/security/requestFiltering' + SingleItemCollectionName = 'hiddenSegments' + SingleItemKeyName = '*' + SingleItemKeyValue = 'appsettings.json' + SingleItemPropertyName = 'segment' + SingleItemPropertyValue = 'appsettings.json' } ) } @@ -78,6 +84,12 @@ try $integerItemKeyValue = $ConfigurationData.AllNodes.IntegerItemKeyValue $integerItemPropertyName = $ConfigurationData.AllNodes.IntegerItemPropertyName $integerItemPropertyValue = $ConfigurationData.AllNodes.IntegerItemPropertyValue + $singleItemFilter = $ConfigurationData.AllNodes.SingleItemFilter + $singleItemCollectionName = $ConfigurationData.AllNodes.SingleItemCollectionName + $singleItemKeyName = $ConfigurationData.AllNodes.SingleItemKeyName + $singleItemKeyValue = $ConfigurationData.AllNodes.SingleItemKeyValue + $singleItemPropertyName = $ConfigurationData.AllNodes.SingleItemPropertyName + $singleItemPropertyValue = $ConfigurationData.AllNodes.SingleItemPropertyValue $startDscConfigurationParameters = @{ Path = $TestDrive @@ -89,6 +101,7 @@ try $filterValue = "$($filter)/$($collectionName)/$($itemName)[@$($itemKeyName)='$($itemKeyValue)']/@$itemPropertyName" $integerFilterValue = "$($integerFilter)/$($integerCollectionName)/$($itemName)[@$($integerItemKeyName)='$($integerItemKeyValue)']/@$integerItemPropertyName" + $singleItemFilterValue = "$($singleItemFilter)/$($singleItemCollectionName)/$($itemName)[@$($singleItemKeyName)='$($singleItemKeyValue)']/@$singleItemPropertyName" Context 'When Adding Collection item' { It 'Should compile and apply the MOF without throwing' { @@ -183,6 +196,53 @@ try } } + Context 'When Adding Single Collection item' { + It 'Should compile and apply the MOF without throwing' { + { + & "$($script:dscResourceName)_SingleItemAdd" -OutputPath $TestDrive -ConfigurationData $configurationData + Start-DscConfiguration @startDscConfigurationParameters + } | Should -Not -Throw + } + + It 'Should be able to call Get-DscConfiguration without throwing' { + { Get-DscConfiguration -Verbose -ErrorAction Stop } | Should -Not -Throw + } + + It 'Should return $true for Test-DscConfiguration' { + Test-DscConfiguration | Should Be $true + } + + It 'Should have the correct value of the configuration property collection item' { + # Get the new value. + $value = (Get-WebConfigurationProperty -PSPath $websitePath -Filter $singleItemFilterValue -Name "." -ErrorAction SilentlyContinue).Value + + $value | Should -Be $singleItemPropertyValue + } + } + + Context 'When Removing Single Collection item' { + It 'Should compile and apply the MOF without throwing' { + { + & "$($script:dscResourceName)_SingleItemRemove" -OutputPath $TestDrive -ConfigurationData $configurationData + Start-DscConfiguration @startDscConfigurationParameters + } | Should -Not -Throw + } + + It 'Should be able to call Get-DscConfiguration without throwing' { + { Get-DscConfiguration -Verbose -ErrorAction Stop } | Should -Not -Throw + } + + It 'Should return $true for Test-DscConfiguration' { + Test-DscConfiguration | Should Be $true + } + + It 'Should remove configuration property' { + $value = (Get-WebConfigurationProperty -PSPath $websitePath -Filter $singleItemFilterValue -Name "." -ErrorAction SilentlyContinue).Value + + $value | Should -BeNullOrEmpty + } + } + # Remove the website we created for testing purposes. if (Get-Website -Name $websiteName) { diff --git a/tests/Integration/DSC_WebConfigPropertyCollection.config.ps1 b/tests/Integration/DSC_WebConfigPropertyCollection.config.ps1 index 8b02a717..86ba5be4 100644 --- a/tests/Integration/DSC_WebConfigPropertyCollection.config.ps1 +++ b/tests/Integration/DSC_WebConfigPropertyCollection.config.ps1 @@ -81,3 +81,44 @@ Configuration DSC_WebConfigPropertyCollection_Integer } } } + +Configuration DSC_WebConfigPropertyCollection_SingleItemAdd +{ + Import-DscResource -ModuleName WebAdministrationDsc + + node localhost + { + WebConfigPropertyCollection IntegrationTest + { + WebsitePath = $Node.WebsitePath + Filter = $Node.SingleItemFilter + CollectionName = $Node.SingleItemCollectionName + ItemName = $Node.ItemName + ItemKeyName = $Node.SingleItemKeyName + ItemKeyValue = $Node.SingleItemKeyValue + ItemPropertyName = $Node.SingleItemPropertyName + ItemPropertyValue = $Node.SingleItemPropertyValue + Ensure = 'Present' + } + } +} + +Configuration DSC_WebConfigPropertyCollection_SingleItemRemove +{ + Import-DscResource -ModuleName WebAdministrationDsc + + node localhost + { + WebConfigPropertyCollection IntegrationTest + { + WebsitePath = $Node.WebsitePath + Filter = $Node.SingleItemFilter + CollectionName = $Node.SingleItemCollectionName + ItemName = $Node.ItemName + ItemKeyName = $Node.SingleItemKeyName + ItemKeyValue = $Node.SingleItemKeyValue + ItemPropertyName = $Node.SingleItemPropertyName + Ensure = 'Absent' + } + } +} diff --git a/tests/Unit/DSC_WebConfigPropertyCollection.Tests.ps1 b/tests/Unit/DSC_WebConfigPropertyCollection.Tests.ps1 index 96edf1aa..9b008676 100644 --- a/tests/Unit/DSC_WebConfigPropertyCollection.Tests.ps1 +++ b/tests/Unit/DSC_WebConfigPropertyCollection.Tests.ps1 @@ -60,6 +60,18 @@ try Ensure = 'Absent' } + $script:absentSingleItemParameters = @{ + WebsitePath = 'MACHINE/WEBROOT/APPHOST' + Filter = 'system.webServer/security/requestFiltering' + CollectionName = 'hiddenSegments' + ItemName = 'add' + ItemKeyName = '*' + ItemKeyValue = 'appsettings.json' + ItemPropertyName = 'segment' + ItemPropertyValue = 'appsettings.json' + Ensure = 'Absent' + } + #region Function Get-TargetResource Describe "$($script:dscResourceName)\Get-TargetResource" { $parameters = @{ @@ -310,6 +322,18 @@ try Assert-MockCalled -CommandName Remove-WebConfigurationProperty -Times 1 -Exactly } } + + Context 'Ensure is absent and single collection item element' { + Mock -CommandName Remove-WebConfigurationProperty -MockWith {} + + It 'Should call the right Mocks' { + Set-TargetResource @script:absentSingleItemParameters + + Assert-MockCalled -CommandName Remove-WebConfigurationProperty -Times 1 -Exactly -ParameterFilter { + $AtElement[$script:absentSingleItemParameters.ItemPropertyName] -eq $script:absentSingleItemParameters.ItemKeyValue + } + } + } } #endregion Function Set-TargetResource