diff --git a/aspnet/fundamentals/hosting.rst b/aspnet/fundamentals/hosting.rst deleted file mode 100644 index 89e0527809ae..000000000000 --- a/aspnet/fundamentals/hosting.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. include:: /../common/stub-topic.txt - -|stub-icon| Hosting -=================== - -.. include:: /../common/stub-notice.txt - -.. _issue: https://github.com/aspnet/Docs/issues/58 \ No newline at end of file diff --git a/aspnet/fundamentals/index.rst b/aspnet/fundamentals/index.rst index 48807819a380..1b406448685f 100644 --- a/aspnet/fundamentals/index.rst +++ b/aspnet/fundamentals/index.rst @@ -24,5 +24,4 @@ Fundamentals request-features servers owin - hosting diff --git a/aspnet/fundamentals/servers.rst b/aspnet/fundamentals/servers.rst index 98eabb0e871d..d9311ec1a645 100644 --- a/aspnet/fundamentals/servers.rst +++ b/aspnet/fundamentals/servers.rst @@ -259,5 +259,4 @@ Because ASP.NET 5 has completely decoupled ASP.NET applications from IIS or any Additional Reading ------------------ -- :doc:`request-features` -- :doc:`hosting` \ No newline at end of file +- :doc:`request-features` \ No newline at end of file diff --git a/aspnet/fundamentals/startup.rst b/aspnet/fundamentals/startup.rst index 67134501ac21..4992d7bdf061 100644 --- a/aspnet/fundamentals/startup.rst +++ b/aspnet/fundamentals/startup.rst @@ -63,7 +63,7 @@ IApplicationEnvironment Provides access to the application properties, such as ``ApplicationName``, ``ApplicationVersion``, and ``ApplicationBasePath``. Available to the ``Startup`` constructor and ``Configure`` method. IHostingEnvironment - Provides the current ``EnvironmentName``, ``WebRootPath``, and web root file provider. Available to the ``Startup`` constructor and ``Configure`` method. Learn more about :doc:`hosting`. + Provides the current ``EnvironmentName``, ``WebRootPath``, and web root file provider. Available to the ``Startup`` constructor and ``Configure`` method. ILoggerFactory Provides a mechanism for creating loggers. Available to the ``Startup`` constructor and ``Configure`` method. Learn more about :doc:`logging`. diff --git a/aspnet/hosting/apppool.rst b/aspnet/hosting/apppool.rst new file mode 100644 index 000000000000..8982cb721bcc --- /dev/null +++ b/aspnet/hosting/apppool.rst @@ -0,0 +1,44 @@ +.. _apppool: + +Application Pools +================= + +By `Sourabh Shirhatti` + +When hosting multiple web sites on a single server, you should consider isolating the applications from each other by running each application in its own application pool. This document provides an overview of how to set up Application Pools to securely host multiple web sites on a single server. + +Application Pool Identity Account +--------------------------------- + +An application pool identity account allows you to run an application under a unique account without having to create and manage domains or local accounts. On IIS 8.0+ the IIS Admin Worker Process (WAS) will create a virtual account with the name of the new application pool and run the application pool's worker processes under this account by default. + +Configuring IIS Application Pool Identities +------------------------------------------- + +In the IIS Management Console, under **Advanced Settings** for your application pool ensure that `Identity` list item is set to use **ApplicationPoolIdentity** as shown in the image below. + +.. image:: apppool/_static/apppool-identity.png + +Securing Resources +------------------ + +The IIS management process creates a secure identifier with the name of the application pool in the Windows Security System. Resources can be secured by using this identity, however this identity is not a real user account and will not show up in the Windows User Management Console. + +To grant the IIS worker process access to your application, you will need to modify the Access Control List (ACL) for the the directory containing your application. + +1. Open Windows Explorer and naviagate to the directory. +2. Right click on the directory and click properties. +3. Under the **Security** tab, click the **Edit** button and then the **Add** button +4. Click the **Locations** and make sure you select your server. + +.. image:: apppool/_static/apppool-adduser.jpg + +5. Enter **IIS AppPool\\DefaultAppPool** in **Enter the object names to select** textbox. +6. Click the **Check Names** button and then click **OK**. + +You can also do this via the command-line by using **ICACLS** tool. + +.. code:: bat + + ICACLS C:\sites\MyWebApp /grant "IIS AppPool\DefaultAppPool" :F + diff --git a/aspnet/hosting/apppool/_static/apppool-adduser.jpg b/aspnet/hosting/apppool/_static/apppool-adduser.jpg new file mode 100644 index 000000000000..7eb55ad4b70d Binary files /dev/null and b/aspnet/hosting/apppool/_static/apppool-adduser.jpg differ diff --git a/aspnet/hosting/apppool/_static/apppool-identity.png b/aspnet/hosting/apppool/_static/apppool-identity.png new file mode 100644 index 000000000000..b5ac182a95a1 Binary files /dev/null and b/aspnet/hosting/apppool/_static/apppool-identity.png differ diff --git a/aspnet/hosting/dataprotection.rst b/aspnet/hosting/dataprotection.rst new file mode 100644 index 000000000000..6d8be4e5c5ce --- /dev/null +++ b/aspnet/hosting/dataprotection.rst @@ -0,0 +1,22 @@ +.. _dataprotection: + +Data Protection +=============== + +By `Sourabh Shirhatti` + +The ASP.NET 5 data protection stack provides a simple and easy to use cryptographic API a developer can use to protect data, including key management and rotation. This document provides an overview of how to configure Data Protection on your server to enable developers to use data protection. + +Create Data Protection Registry Hive +------------------------------------ + +By default, keys are not persisted outside of the current process. When the process shuts down, all generated keys will be lost. To persist keys for an application hosted in IIS, you must create registry hives for each application pool to store the keys. You should use the `Provisioning PowerShell script `_ for each application pool you will be hosting ASP.NET 5 applications under. This script will create a special registry key in the HKLM registry that is ACLed only to the worker process account. Keys are encrypted at rest using DPAPI. + +.. note:: A developer can consume the Data Protection APIs to encrypt data at rest using a X.509 certificates. + +Machine Wide Policy +------------------- + +The data protection system has limited support for setting default machine-wide policy for all applications that consume the data protection APIs. For more information on how to configure the machine wide policy have a look at :ref:`this article `. + + diff --git a/aspnet/hosting/directory-structure.rst b/aspnet/hosting/directory-structure.rst new file mode 100644 index 000000000000..97629fe5cc0b --- /dev/null +++ b/aspnet/hosting/directory-structure.rst @@ -0,0 +1,19 @@ +.. _directory-structure: + +Directory Structure +=================== + +By `Sourabh Shirhatti` + + +In ASP.NET 5, the application directory comprises of three sub-directories. This is unlike previous versions of ASP.NET where the entire application lived inside the web root directory. The recommended permissions for each of the directories are specified in the table below. + +======= ============== =========== +Folder Permissions Description +======= ============== =========== +approot Read & Execute Contains the application, app config files, packages and the DNX runtime. +logs Read & Write The default folder for HTTP Platform Handler to redirect logs to. +wwwroot Read & Execute Contains the static assets +======= ============== =========== + +The **wwwroot** directory represents the web root of the application. The physical path for the IIS site should point to the web root directory. While deploying a web site, a developer will need access to the entire application directory. \ No newline at end of file diff --git a/aspnet/hosting/http-platformhandler.rst b/aspnet/hosting/http-platformhandler.rst new file mode 100644 index 000000000000..4088d6d4522d --- /dev/null +++ b/aspnet/hosting/http-platformhandler.rst @@ -0,0 +1,47 @@ +.. _http-platformhandler: + +HTTP Platform Handler +===================== + +By `Sourabh Shirhatti` + +In ASP.NET 5, the web application is hosted by an external process outside of IIS. The HTTP Platform Handler is an IIS 7.5+ module which is responsible for process management of http listeners and to proxy requests to processes that it manages. This document provides an overview of how to configure the HTTP Platform Handler module for shared hosting of ASP.NET 5. + +Installing the HTTP Platform Handler +------------------------------------ + +To get started with hosting with ASP.NET 5 applications you will need to install the HTTP Platform Handler version 1.2 or higher on an IIS 7.5 or higher server. Download links are below + +* `64 bit HTTP PlatformHandler (x64) `_ +* `32 bit HTTP PlatformHandler (x86) `_ + + +Configuring the HTTP Platform Handler +------------------------------------- + +The HTTP Platform Handler is configured via a site or application's *web.config* file and has its own configuration section within ``system.webServer - httpPlatform``. The `HTTP Platform Handler configuration reference whitepaper `_ describes in detail how to modify Configuration Attributes for the HTTP PlatformHandler module. + +.. note:: + You may need to unlock the handlers section of *web.config*. Follow the instructions :ref:`here `. + +Log Redirection +--------------- + +The HTTP Platform Handler module can redirect ``stdout`` and ``stderr`` logs to disk by setting the ``stdoutLogEnabled`` and ``stdoutLogFile`` properties of the ``httpPlatform`` attribute. However, the HTTP Platform Handler module does not rotate logs and it is the responsibilty of the hoster to limit the disk space the logs consume. + +.. literalinclude:: http-platformhandler/sample/web.config + :language: xml + :lines: 12-16,20 + + +Setting Environment Variables +----------------------------- + +The HTTP Platform Handler module allows you specify environment variables for the process specified in the ``processPath`` setting by specifying them in ``environmentVariables`` child attribute to the ``httpPlatform`` attribute. The example below illustrates how you would use it. + +.. literalinclude:: http-platformhandler/sample/web.config + :language: xml + :lines: 12-20 + +.. note:: + There is a `known issue `_ known issue with ``dnu publish`` where it removes all child attributes of the ``httpPlatform`` attribute. diff --git a/aspnet/hosting/http-platformhandler/sample/web.config b/aspnet/hosting/http-platformhandler/sample/web.config new file mode 100644 index 000000000000..a6c2ffb202bd --- /dev/null +++ b/aspnet/hosting/http-platformhandler/sample/web.config @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/aspnet/hosting/index.rst b/aspnet/hosting/index.rst new file mode 100644 index 000000000000..617504e37720 --- /dev/null +++ b/aspnet/hosting/index.rst @@ -0,0 +1,15 @@ +Hosting +======= + +By `Sourabh Shirhatti` + +The hosting docs provide an overview of how to host ASP.NET 5. Hosters who offer ASP.NET hosting will be able to use the setup and configuration recommendations to integrate ASP.NET 5 into their hosting solution. This document should also serve as a guide for any enviroment where multiple discrete users will be running web sites on a single server or web farm. + +.. toctree:: + :titlesonly: + + http-platformhandler + directory-structure + apppool + servicing + dataprotection diff --git a/aspnet/hosting/servicing.rst b/aspnet/hosting/servicing.rst new file mode 100644 index 000000000000..ce28b20f45bc --- /dev/null +++ b/aspnet/hosting/servicing.rst @@ -0,0 +1,30 @@ +.. _hosting-servicing: + +Servicing +========= + +By `Sourabh Shirhatti` + +ASP.NET 5 supports servicing of runtime components (DNX) and packages through Microsoft Update, which will deliver updates to patch any vulnerabilities when they are discovered. This document provides an overview of how to setup your Windows Server correctly to receive updates. + +Breadcrumbs Directory +--------------------- + +All serviceable assemblies will leave a breadcrumb in the ``BreadcrumbStore`` Directory. At the time of servicing Microsoft Update looks in this directory to figure out which assemblies are used on the server and require patching. The ``BreadcrumbStore`` directory must be protected by ACLs to prevent rogue applications from deleting entries from this directory. To create the ``BreadcrumbStore`` directory and set the ACLs securely, run the following powershell script below in an elevated prompt: to create the ``BreadcrumbStore`` directory and set ACLs on it correctly. + + +.. code-block:: powershell + + $breadcrumbFolder = $env:ALLUSERSPROFILE + '\Microsoft DNX\BreadcrumbStore' + New-Item -Force -Path $breadcrumbFolder -ItemType "Directory" + $ACL = Get-Acl -Path $breadcrumbFolder + # Clear any permissions + $ACL.SetAccessRuleProtection($true, $false) + # Set new permissions + $ACL.SetSecurityDescriptorSddlForm("O:SYG:SYD:P(A;OICI;CCDCSWWPLORC;;;WD)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)") + Set-Acl -Path $breadcrumbFolder -AclObject $ACL + +Servicing Directory +------------------- + +At the time of loading an asset, DNX will check against an index file in the ``Servicing`` directory to determine whether it should load a patched version instead of what it would normally load. The index file is updated by Microsoft Update during servicing to point to the location of the patched version of the asset on disk, which will reside in the ``Servicing`` directory. The index file defaults to ``%PROGRAMFILES%\Microsoft DNX\Servicing``, but you can change this by setting the ``DNX_SERVICING`` environment variable to a different path. diff --git a/aspnet/index.rst b/aspnet/index.rst index 2aaf418b51a6..0a8be2766e61 100644 --- a/aspnet/index.rst +++ b/aspnet/index.rst @@ -38,6 +38,7 @@ Topics performance/index migration/index contribute/index + hosting/index Related Resources ----------------- diff --git a/aspnet/publishing/iis.rst b/aspnet/publishing/iis.rst index 0c8dbdb30cd8..addc2776e774 100644 --- a/aspnet/publishing/iis.rst +++ b/aspnet/publishing/iis.rst @@ -66,6 +66,8 @@ IIS server configuration .. image:: pubIIS/_static/role-services.png +.. _unlock-handlers: + 3. Unlock the configuration section. - Launch IIS Manager and select the server in the **Connections** pane on the left (see image below). diff --git a/common/authors.txt b/common/authors.txt index d23a58d6e447..c385c959d6f5 100644 --- a/common/authors.txt +++ b/common/authors.txt @@ -10,3 +10,4 @@ .. _David Paquette: https://github.com/dpaquette .. _Scott Addie: http://scottaddie.com .. _Sayed Ibrahim Hashimi: https://github.com/sayedihashimi +.. _Sourabh Shirhatti: https://twitter.com/sshirhatti \ No newline at end of file diff --git a/mvc/controllers/dependency-injection.rst b/mvc/controllers/dependency-injection.rst index b5a534eada63..c240433fd217 100644 --- a/mvc/controllers/dependency-injection.rst +++ b/mvc/controllers/dependency-injection.rst @@ -1,9 +1,6 @@ Dependency Injection and Controllers ==================================== -.. _dependency-injection-controllers: - -|stub-icon| Dependency Injection and Controllers By `Steve Smith`_ ASP.NET MVC 6 controllers should request their dependencies explicitly via their constructors. In some instances, individual controller actions may require a service, and it may not make sense to request at the controller level. In this case, you can also choose to inject a service as a parameter on the action method.