Troubleshooting Common MSDeploy Issues
This article is meant to provide a quick reference troubleshooting guide to help with the most frequently encountered problems and questions. It does not contain a full list of issues and problems, but will be updated with the latest issues and workarounds as the need arises.
Issues covered in this article:
- Connection Issues and Remoting
- Logging
- Skip Replace Rules
- Enabling/Disabling Link Extensions
- Insufficient Privileges (401)
- Working with IIS6
- If None of the Above Works
Connection Issues and Remoting
MSDeploy agent
If you are syncing over the MSDeploy agent, make sure the corresponding MSDeploy service is started on the remote machine:
net start msdepsvc
Handler
(Web Management Service)Similar to the agent case, if you are syncing over the handler, make sure the corresponding service is started:
net start wmsvc
Default TCP Port
MSDeploy operates through port 8172 by default. Enable port 8172 through the firewall by running
netsh firewall add portopening TCP 8172 WdeployAgent
Logging
Fatal errors are logged in %TEMP%\Web_Deployment_Agent_Service.log. Where %TEMP% refers to the service identity's temp folder which by default is Windows\ServiceProfiles\NetworkService\AppData\Local\Temp\MSDepSvc
Skip Replace Rules
If some destination settings are different from source settings (e.g. different system drives in file paths), you can write a skip replace rule to change the setting. Thus, if you sync an IIS6 site with the content that resides on c:\wwwroot\inetpub to another site that is mapped to d:\wwwroot\inetpub, you’d write the following replace rule to make the 1-liner sync possible:
msdeploy.exe -verb:sync -source:metaKey=/lm/w3svc/2 -dest:metaKey=/lm/w3svc/3 -replace:objectName=metaProperty,scopeAttributeName=name,scopeAttributeValue=path,targetAttributeName=value,match="e:",replace="d:"
An excellent resource for writing skip replace rules is the blog post: How to write skip and replace rules for MSDeploy
Enabling/Disabling Link Extensions
If you copy content of a webserver/site separately and don’t want it to be copied during your MSDeploy sync operation, you can do it by using -disableLink:ContentExtension command line option.
Example (sync one server to another w/o content):
msdeploy -verb:sync -source:webserver -dest:webserver,computerName=URLtoRemoteAgent
If you sync a site and its app pool is not pulled in (default behavior), you can enable pulling in the app pool by using the –enableLink:AppPoolExtension switch.
Example (create a backup of a site with app pool):
msdeploy -verb:sync –source:appHostConfig=”MySite” –dest:package=”c:\BackupUpOfSiteWithAppPool.zip” –enableLink:AppPoolExtension
Insufficient Privileges (401)
Things to check:
ACLs
If you are syncing as an IIS user, the content path that you are trying to access should be ACL’ed for read/write access for NT Service\WMSvc identity.
AppPoolIndentity
If you think you might have problems with app pool identity, try to run the app pool with admin privileges, see if the problem persists, fix permissions problem if necessary and set the app pool back its original identity.
Delegation Rules
If you are running a sync operation as a non-admin account, make sure delegation rules are set up correctly on the remote server. For example, to allow all users to import iisApp packages and set ACLs within user connection scope, add the rule below to "system.webServer/management" section in administration.config file.
<!-- set allowAdministrators to "false" if you don't want administrators to bypass delegation rules --> <delegation allowAdministrators="false"> <!-- Will attempt to perform the operations as the current identity. If you want to run these opearations as a specific user, uncomment "runAs" below --> <rule providers="iisapp,createapp,contentpath,setAcl" actions="*" path="{userScope}"> <permissions> <user name="*" isRole="false" accessType="Allow" /> </permissions> <!-- <runAs identityType="SpecificUser" userName="iisAppUser" password="iisUserPassword" /> --> </rule> </delegation>
Another useful reference on automating the creation of delegation rules in C# is the following IIS.NET article: Configure the Web Deployment Handler
Server Certificates
How does your client validate server certificates?
- If you are running a command line and trust the server, specify the –allowUntrusted switch to accept untrusted certificates.
- If you wrote your own client to interface with MSDeploy APIs and sync to a remote machine, make sure to provide a certificate validation delegate to validate the server certificate.
Another great reference on the subject of certificate validation delegate is the MSDN article: Did you know... establishing a remote connection to a IIS server with self-issued certificate will require a certificate validation delegate?
Working with IIS6
MSDeploy does work with IIS. Moreover, MSDeploy can migrate a site from IIS6 to IIS7. Another excellent article about how to migrate a site from IIS6 to IIS7: Migrate from IIS 6.0 to IIS 7.0. Below are some important tips and tricks that will help you get around common problems.
Webserver Provider
To sync the whole IIS6 server, you need to user webserver60 provider instead of webserver, which is reserved for IIS7 servers
Specific Metabase Path
To sync a specific metabase path (a site or application), you need to use metakey provider
Site Identifiers
To specify a siteId for your metabase path, you need to find out what identifier your site/application has. Run the following command to list metabase paths:
adsutil enum /p w3svc
Microsoft (R) Windows Script Host Version 5.7
Copyright (C) Microsoft Corporation. All rights reserved.[/w3svc/Info]
[/w3svc/Filters]
If None of the Above Works
Run your command with -debug switch and post your question on MSDeploy forum with the stack trace.
Hope this helps!