IIS on Nano Server
Applies To: Windows Server Technical Preview
Overview of IIS on Nano Server
You can install the Internet Information Services (IIS) server role on Nano Server by using the -Packages parameter with Microsoft-NanoServer-IIS-Package. For information about configuring Nano Server, including installing packages, see Get Started with Nano Server.
In this release of Nano Server, the following IIS features are available:
Feature |
Enabled by default |
---|---|
Common HTTP Features |
|
Default document |
x |
Directory browsing |
x |
HTTP Errors |
x |
Static content |
x |
HTTP redirection |
|
Health and Diagnostics |
|
HTTP logging |
x |
Custom logging |
|
Request monitor |
|
Tracing |
|
Performance |
|
Static content compression |
x |
Dynamic content compression |
|
Security |
|
Request filtering |
x |
Basic authentication |
|
Client certificate mapping authentication |
|
Digest authentication |
|
IIS client certificate mapping authentication |
|
IP and domain restrictions |
|
URL authorization |
|
Windows authentication |
|
Application Development |
|
Application initialization |
|
CGI |
|
ISAPI extensions |
|
ISAPI filters |
|
Server-side includes |
|
WebSocket protocol |
|
Management Tools |
|
IISAdministration module for Windows PowerShell |
x |
A series of articles on other configurations of IIS (such as using ASP.NET, PHP, and Java), as well as other related content is published at https://iis.net/learn.
Installing IIS on Nano Server
You can install this server role either offline (with the Nano Server off) or online (with the Nano Server running); offline installation is the recommended option.
For offline installation, add the package with the -Packages parameter of New-NanoServerImage, as in this example:
New-NanoServerImage -MediaPath f:\ -BasePath .\Base -TargetPath .\Nano1.vhd -GuestDrivers -Packages Microsoft-NanoServer-IIS-Package
If you have an existing VHD file, you can install IIS offline with DISM.exe by navigating to the directory where the Nano Server VHD is, mount the VHD, and use the Add-Package option. The specific commands are:
md mountdir
dism\dism /Mount-Image /ImageFile:.\NanoServer.vhd /Index:1 /MountDir:.\mountdir
dism\dism /Add-Package /PackagePath:.\packages\Microsoft-NanoServer-IIS-Package.cab /Image:.\mountdir
dism\dism /Add-Package /PackagePath:.\packages\en-us\Microsoft-NanoServer-IIS-Package.cab /Image:.\mountdir
dism\dism /Unmount-Image /MountDir:.\MountDir /Commit
Note
Note that Step 4 adds the language pack--this example installs EN-US.
At this point you can start the Nano Server with IIS.
Installing IIS on Nano Server online
Though offline installation of the server role is recommended, you might need to install it online (with the Nano Server running) in container scenarios. To do this, follow these steps:
Copy the Packages folder from the installation media locally to the running Nano Server (for example, to C:\packages).
Create a new Unattend.xml file, either on another computer (followed by copying the file to the Nano Server) or remotely on the Nano Server by using Windows PowerShell remoting. To do the latter, use New-Item unattend.xml followed by Psedit unattend.xml to copy and paste this XML content into the XML file you created:
<?xml version="1.0" encoding="utf-8"?> <unattend xmlns="urn:schemas-microsoft-com:unattend"> <servicing> <package action="install"> <assemblyIdentity name="Microsoft-NanoServer-IIS-Package" version="10.0.10586.0" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" /> <source location="c:\packages\Microsoft-NanoServer-IIS-Package.cab" /> </package> <package action="install"> <assemblyIdentity name="Microsoft-NanoServer-IIS-Package" version="10.0.10586.0" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="en-US" /> <source location="c:\packages\en-us\Microsoft-NanoServer-IIS-Package.cab" /> </package> </servicing> <cpi:offlineImage cpi:source="" xmlns:cpi="urn:schemas-microsoft-com:cpi" /> </unattend>
In the new XML file you created (or copied), edit C:\packages to the directory you copied the content of Packages to.
Switch to the directory with the newly created XML file and run
dism /online /apply-unattend:.\unattend.xml
You will receive a 0x80004005 error ("DISM failed. No operation was performed"), but you can safely ignore it. The IIS server role is correctly installed.
Confirm that the IIS package and its associated language pack is installed correctly by running:
dism /online /get-packages
You should see "Package Identity : Microsoft-NanoServer-IIS-Package~31bf3856ad364e35~amd64~en-US~10.0.10586.0" listed twice, once for Release Type : Language Pack and once for Release Type : Feature Pack.
Start the W3SVC service either with net start w3svc or by restarting the Nano Server.
Starting IIS
Once IIS is installed and running, it is ready to serve web requests. Verify that IIS is running by browsing the default IIS web page at https://<IP address of Nano Server>. On a physical computer, you can determine the IP address by using the Recovery Console. On a virtual machine, you can get the IP address by using a Windows PowerShell prompt and running:
Get-VM -name <VM name> | Select -ExpandProperty networkadapters | select IPAddresses
If you are not able to access the default IIS web page, double-check the IIS installation by looking for the c:\inetpub directory on the Nano Server.
Enabling and disabling IIS features
A number of IIS features are enabled by default when you install the IIS role (see the table in the "Overview of IIS on Nano Server" section of this topic). You can enable (or disable) additional features in three ways:
Using the IISAdministration module for Windows PowerShell remotely
Using AppCmd.exe remotely
Manually editing the IIS configuration store
This topic will detail using the IISAdministration module. For examples of using AppCmd.exe, see IISModules Overview. For general information about the IISAdminstration module, see IISAdministration PowerShell Cmdlets.
Each feature of IIS exists as a set of configuration elements. For example, the Windows authentication feature comprises these elements:
Section |
Configuration elements |
---|---|
<globalModules> |
<add name="WindowsAuthenticationModule" image="%windir%\System32\inetsrv\authsspi.dll |
<modules> |
<add name="WindowsAuthenticationModule" lockItem="true" /> |
<windowsAuthentication> |
<windowsAuthentication enabled="false" authPersistNonNTLM="true"> <providers> <add value="Negotiate" /> <add value="NTLM" /> </providers> </windowsAuthentication> |
The full set of these configuration elements for all of the IIS features available in this release is included in Appendix 1 of this topic.
The IISAdministration module of Windows PowerShell allows you to easily add or remove these configuration elements to the applicationhost.config file. Here are three examples using this method: one for installing the Windows authentication feature, one for removing the Windows authentication feature, and one for installing the Default Document feature.
Example: installing Windows authentication
In a Windows PowerShell remote session console on the Nano Server, import the Windows PowerShell module for IISAdministration with Import-Module IISAdministration.
Add the configuration elements to the <globalModules> section with this scriptlet:
# refresh the in-memory image of the config Reset-IISServerManager -Confirm:$false $section = Get-IISConfigSection "system.webServer/globalModules" $collection = Get-IISConfigCollection -ConfigElement $section New-IISConfigCollectionElement $collection -ConfigAttribute @{"name"="WindowsAuthenticationModule";"image"="%windir%\System32\inetsrv\authsspi.dll"}
Add the configuration elements to the <modules> section with this scriptlet:
$section = Get-IISConfigSection "system.webServer/modules" $collection = Get-IISConfigCollection -ConfigElement $section New-IISConfigCollectionElement $collection -ConfigAttribute @{"name"="WindowsAuthenticationModule"}
Add the configuration elements to the <windowsAuthentication> section with this scriptlet. You might find it helpful to view the IIS schema file (%windir%\system32\inetsrv\config\schema\iis_schema.xml) to see how to navigate through the XML.
# delay writes for the New-, Set-* calls, since we're writing to the same section multiple times and we don't want to have to # keep calling Get-IISConfigSection to get a fresh copy. Start-IISCommitDelay $section = Get-IISConfigSection "system.webServer/security/authentication/windowsAuthentication" Set-IISConfigAttributeValue -ConfigElement $section -AttributeName "enabled" -AttributeValue $false Set-IISConfigAttributeValue -ConfigElement $section –AttributeName "authPersistNonNTLM" -AttributeValue $true $collection = Get-IISConfigElement -ConfigElement $section –ChildElementName "providers" | Get-IISConfigCollection New-IISConfigCollectionElement -ConfigCollection $collection –ConfigAttribute @{"value"="Negotiate"} New-IISConfigCollectionElement -ConfigCollection $collection -ConfigAttribute @{"value"="NTLM"} # commit the changes to disk Stop-IISCommitDelay
Example: uninstalling Windows authentication
To uninstall a feature, delete the <globalModules> and <modules> elements, and then delete the contents of the <windowsAuthentication> section (in this example). To do this with Windows PowerShell, pipe commands transfer the output of one cmdlet to following cmdlets.
The exact operations required might vary for different features. For example, for Windows authentication, the <windowsAuthentication> section has five attributes and two child elements. Deleting the two collection elements and the providers element is adequate for uninstalling the feature, but you could delete all five aReplaceThisText
ttributes and the <extendedProtection> element as well.
In a Windows PowerShell remote session console on the Nano Server, import the Windows PowerShell module for IISAdministration with Import-Module IISAdministration.
Run this scriptlet:
Get-IISConfigSection "system.webServer/globalModules" | Get-IISConfigCollection | ` Remove-IISConfigCollectionElement -ConfigAttribute @{"name"="WindowsAuthenticationModule"} -Confirm:$false Get-IISConfigSection "system.webServer/modules" | Get-IISConfigCollection | ` Remove-IISConfigCollectionElement -ConfigAttribute @{"name"="WindowsAuthenticationModule"} -Confirm:$false
Run this scriptlet:
Start-IISCommitDelay $section = Get-IISConfigSection "system.webServer/security/authentication/windowsAuthentication" Remove-IISConfigAttribute -ConfigElement $section -AttributeName "enabled" -confirm:$false Remove-IISConfigAttribute -ConfigElement $section -AttributeName "authPersistNonNTLM" Get-IISConfigElement -ConfigElement $section -ChildElementName "providers" | Remove-IISConfigElement -Confirm:$false # commit the changes to disk Stop-IISCommitDelay
Example: Installing Default Document
Though Default Document is installed by default, it makes a good example because it includes further elements such as StaticFile in the <handlers> section. In addition to adding elements to <globalModules> and <modules> as in the Windows authentication example, you must also add or modify these additional elements. Before installing or uninstalling any IIS features, refer to the detailed elements in the Appendix to note all elements that you must modify.
Note
The order that elements are listed in the <modules> section is important. See Execution order of modules in IIS7 for more details.
In a Windows PowerShell remote session console on the Nano Server, import the Windows PowerShell module for IISAdministration with Import-Module IISAdministration.
Add the required elements to <globalModules> and <modules> with scriptlets similar to the ones in Steps 2 and 3 of the Windows authentication example.
Add or modify the StaticFile element in the <handlers> section and add additional elements that <defaultDocument> requires with this scriptlet:
# refresh the in-memory image of the config Reset-IISServerManager -Confirm:$false # delay writes until we're done working with this section Start-IISCommitDelay $collection = Get-IISConfigSection "system.webServer/handlers" | Get-IISConfigCollection $element = Get-IISConfigCollectionElement $collection -ConfigAttribute @{"name"="StaticFile"} if($element -eq $null) { # we didn't find the element, so create it New-IISConfigCollectionElement $collection -ConfigAttribute @{"name"="StaticFile";"path"="*"; ` "verb"="*";"modules"="DefaultDocumentModule";"resourceType"="Either";"requireAccess"="Read"} } else { # we found the element, so read the modules attribute $modules = Get-IISConfigAttributeValue -ConfigElement $element -AttributeName "modules" if(-not $modules.Contains("DefaultDocumentModule")) { $modules = "$modules,DefaultDocumentModule" Set-IISConfigAttributeValue -ConfigElement $element -AttributeName "modules" -AttributeValue $modules } } # now commit the changes to disk Stop-IISCommitDelay
Other common IIS configuration tasks
Creating websites
Use this cmdlet:
PS D:\> New-IISSite -Name TestSite -BindingInformation "*:80:TestSite" -PhysicalPath c:\test
You can then run Get-IISSite to verify the state of the site (returns the web site name, ID, state, physical path, and bindings).
Deleting web sites
Run Remove-IISSite -Name TestSite -Confirm:$false.
Creating virtual directories
You can create virtual directories by using the IISServerManager object returned by Get-IISServerManager, which exposes the .NET Microsoft.Web.Administration.ServerManager API. In this example, these commands access the "Default Web Site" element of the Sites collection and the root application element ("/") of the Applications section. They then call the Add() method of the VirtualDirectories collection for that application element to create the new directory:
PS C:\> $sm = Get-IISServerManager
PS C:\> $sm.Sites["Default Web Site"].Applications["/"].VirtualDirectories.Add("/DemoVirtualDir1", "c:\test\virtualDirectory1")
PS C:\> $sm.Sites["Default Web Site"].Applications["/"].VirtualDirectories.Add("/DemoVirtualDir2", "c:\test\virtualDirectory2")
PS C:\> $sm.CommitChanges()
Creating application pools
Similarly you can use Get-IISServerManager to create application pools:
PS C:\> $sm = Get-IISServerManager
PS C:\> $sm.ApplicationPools.Add("DemoAppPool")
Configuring HTTPS and certificates
Use the Certoc.exe utility to import certificates, as in this example, which shows configuring HTTPS for a website on a Nano Server:
On another computer that is not running Nano Server, create a certificate (using your own certificate name and password), and then export it to c:\temp\test.pfx.
$newCert = New-SelfSignedCertificate -DnsName "www.foo.bar.com" -CertStoreLocation cert:\LocalMachine\my
$mypwd = ConvertTo-SecureString -String "YOUR_PFX_PASSWD" -Force -AsPlainText
Export-PfxCertificate -FilePath c:\temp\test.pfx -Cert $newCert -Password $mypwd
Copy the test.pfx file to the Nano Server computer.
On the Nano Server, import the certificate to the "My" store with this command:
certoc.exe -ImportPFX -p YOUR_PFX_PASSWD My c:\temp\test.pfx
Retrieve the thumbprint of this new certificate (in this example, 61E71251294B2A7BB8259C2AC5CF7BA622777E73) with Get-ChildItem Cert:\LocalMachine\my.
Add the HTTPS binding to the Default Web Site (or whatever website you want to add the binding to) by using these Windows PowerShell commands:
$certificate = get-item Cert:\LocalMachine\my\61E71251294B2A7BB8259C2AC5CF7BA622777E73 # Use your actual thumbprint instead of this example $hash = $certificate.GetCertHash() Import-Module IISAdministration $sm = Get-IISServerManager $sm.Sites["Default Web Site"].Bindings.Add("*:443:", $hash, "My", "0") # My is the certificate store name $sm.CommitChanges()
You could also use Server Name Indication (SNI) with a specific host name with this syntax: $sm.Sites["Default Web Site"].Bindings.Add("*:443:www.foo.bar.com", $hash, "My", "Sni".
Appendix 1: Elements of HTTP features
Each feature of IIS exists as a set of configuration elements. This appendix lists the configuration elements for all of the features in this release of Nano Server
Common HTTP features
Default document
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
|
|
The StaticFile <handlers> entry might already be present; if so, just add "DefaultDocumentModule" to the <modules> attribute, separated by a comma.
Directory browsing
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
The StaticFile <handlers> entry might already be present; if so, just add "DirectoryListingModule" to the <modules> attribute, separated by a comma.
HTTP errors
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Static content
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
The StaticFile <handlers> entry might already be present; if so, just add "StaticFileModule" to the <modules> attribute, separated by a comma.
HTTP redirection
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Health and diagnostics
HTTP logging
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Custom logging
Section |
Configuration elements |
---|---|
|
|
|
|
Request monitor
Section |
Configuration elements |
---|---|
|
|
Tracing
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Performance
Static content compression
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Dynamic content compression
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Security
Request filtering
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Basic authentication
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Client certificate mapping authentication
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Digest authentication
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
IIS client certificate mapping authentication
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
IP and domain restrictions
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
URL authorization
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Windows authentication
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
Application development
Application initialization
Section |
Configuration elements |
---|---|
|
|
|
|
CGI
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
ISAPI extensions
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
ISAPI filters
Section |
Configuration elements |
---|---|
|
|
|
|
Server-side includes
Section |
Configuration elements |
---|---|
|
|
|
|
|
|
|
|
WebSocket protocol
Section |
Configuration elements |
---|---|
|
|
|
|