Merge pull request #32 from MicrosoftDocs/master

Troubleshooting, connectivity updates

docs/reference/connectivity.md

@@ -27,7 +27,7 @@ To ensure optimal performance, by default Visual Studio Live Share automatically
 
 The direct connections are authenticated via a cloud based mechanism to ensure security but require a port between 5990 and 5999 be opened to enable the connectivity. As a result, when sharing for the first time your desktop firewall may prompt you open a port. Accepting this is optional as ignoring it will simply cause Live Share to always use the relay when in auto mode.
 
-All connections in Visual Studio Live Share are SSH or SSL encrypted and authenticated against a central service to ensure that only those in the collaboration session can gain access to its content. In addition, Live Share's internet relay does not persist any traffic routed through it and does not "snoop" the traffic in any way.
+All connections in Visual Studio Live Share are SSH or SSL encrypted and authenticated against a central service to ensure that only those in the collaboration session can gain access to its content. In addition, Live Share's cloud relay does not persist any traffic routed through it and does not "snoop" the traffic in any way.
 
 ## Changing the connection mode
 
@@ -41,40 +41,67 @@ If you would prefer to disable direct or relayed connections or are simply troub
 
 To change the mode:
 
-- **VS:** Go to Tools > Options > Live Share, select the mode from the "Connection Mode" dropdown and then restart VS.
-- **VS Code:** Edit settings.json (File > Preferences > Settings) and add one of the following and then restart VS Code:
+**VS:** 
+1. Go to Tools > Options > Live Share
+2. Select the mode from the "Connection Mode" dropdown
+3. Restart VS.
 
-    - ``"liveshare.connectionMode":"auto"``
-    - ``"liveshare.connectionMode":"direct"``
-    - ``"liveshare.connectionMode":"relay"``
+**VS Code:**:
+1. Edit settings.json (File > Preferences > Settings)
+2.  Set `"liveshare.connectionMode"` to `"auto"`, `"direct"`, or `"relay"` depending on your preference.
+3.  Restart VS Code.
 
 ## Requirements for connection modes
 
 The specific ports and URLs that need to be available for Live Share to function will vary depending on the connection mode you are in.
 
-| Mode | Requirements | Troubleshooting |
-|------|----------------|----------------------|
-| All | Access to *.liveshare.vsengsaas.visualstudio.com on port 80/443 | Ensure your corporate or personal network firewall allows you to connect to this domain. Enter https://insiders.liveshare.vsengsaas.visualstudio.com in a browser and verify you land at the VS Live Share home page. |
-| All (VS Code) | Access to download.visualstudio.microsoft.com and download.microsoft.com on port 443 | Ensure your corporate or personal network firewall allows you to connect to this domain. |
+| Mode | Client Access Requirement | Troubleshooting |
+|------|--------------|-----------------|
+| Any | Outbound access to *.liveshare.vsengsaas.visualstudio.com:443 | Ensure your corporate or personal network firewall allows you to connect to this domain. Enter https://insiders.liveshare.vsengsaas.visualstudio.com in a browser and verify you land at the VS Live Share home page. |
+| Any (VS Code) | Outbound access to:<ul><li>download.microsoft.com:443</li><li>download.visualstudio.microsoft.com:443</li></ul> | Ensure your corporate or personal network firewall allows you to connect to this domain. |
 | Auto | Auto-switches. See direct and relay modes. | Switch to direct or relay mode to troubleshoot. |
-| Direct | A port in the range 5990 - 5999 needs to be open on the host's machine and guests need to be able to directly connect to each other. (See [this feature request](https://github.com/MicrosoftDocs/live-share/issues/60) for a proposed improvement.) | Verify "vsls-agent" is not blocked by your desktop firewall software for this port range and that you can ping one another. While Windows and other desktop software should prompt you the first time the agent starts up, we have seen instances where group policies prevent this from happening and you will need to [manually add the entry](#manually-adding-a-firewall-entry). |
-| Relay | Access to *.servicebus.windows.net on port 80/443. | Ensure your corporate or personal network firewall allows you to connect to this domain. |
+| Direct | Hosts: A port in the range 5990 - 5999 needs to be opened to accept inbound local network connections.<br /><br />Guests: A network route and outbound access to the host on this same port. | Verify "vsls-agent" is not blocked by your desktop firewall software for this port range and that you can ping one another. While Windows and other desktop software should prompt you the first time the agent starts up, we have seen instances where group policies prevent this from happening and you will need to [manually add the entry](#manually-adding-a-firewall-entry). |
+| Relay | Outbound access to *.servicebus.windows.net:443. | Ensure your corporate or personal network firewall allows you to connect to this domain. |
 
 ## Manually adding a firewall entry
 
-As outlined above, your personal firewall needs to allow **vsls-agent** to accept connections in the port range 5990-5999. If you want to use direct mode but have found that your firewall does not have vsls-agent entry, you can add it from one of the following locations:
+As outlined above, your personal firewall needs to allow **vsls-agent** to accept connections in the port range 5990-5999. If you want to use direct mode but have found that your firewall does not have vsls-agent entry, you can add manually. How you do this will vary based on your firewall software, but you can find information about **[configuring the Windows Firewall here](https://docs.microsoft.com/en-us/windows/security/identity-protection/windows-firewall/create-an-inbound-program-or-service-rule)**.
+
+You can find the agent executable in one of the following locations.
+
+**VS Code Agent Location**
+
+Substitute **VERSION** for the extension version number in one of the paths below:
+
+- **macOS, Linux**
+
+    `$HOME/.vscode/extensions/ms-vsliveshare.vsliveshare-VERSION/dotnet_modules/vsls-agent`
+
+- **Windows**
+
+    `%USERPROFILE%\.vscode\extensions\ms-vsliveshare.vsliveshare-VERSION\dotnet_modules\vsls-agent.exe`
+
+**Visual Studio Agent Location**
+
+The Visual Studio location is more dynamic, but you can follow these steps to find the executable:
+
+1. Navigate to your VS install location. This is typically `C:\Program Files (x86)\Microsoft Visual Studio\EDITION` where **EDITION** is Community, Enterprise, etc
+
+2. Run a search for `vsls-agent.exe` in under the **IDE\Extensions** sub-folder.
+
+## Proxies
+
+Visual Studio Live Share currently has some limitations around proxy use. **Proxy support is currently limited to direct mode due a known issue.** See [above](#changing-the-connection-mode) for how to switch to direct mode.
 
-VS Code (substitute **VERSION** for the extension version):
+Next, while automatic proxy settings should work on Windows, when using macOS or Linux (and certain proxies with Windows) the **HTTP_PROXY** and **HTTPS_PROXY** environment variables will need to be set *globally*.
 
-- **Windows:** %USERPROFILE%\\.vscode\extensions\ms-vsliveshare.vsliveshare-*VERSION*\dotnet_modules\win7-x86\vsls-agent.exe
-- **macOS:** $HOME/.vscode/extensions/ms-vsliveshare.vsliveshare-*VERSION*/dotnet_modules/osx.10.10-x64/vsls-agent
+If your proxy doesn't automatically set these for you, you can manually set the variables in the following form:
 
-Visual Studio:
+`HTTPS_PROXY=https://proxy-ip-address:proxyport`
 
-- Run a search for vsls-agent.exe in your VS install location under **IDE\Extensions**
-- The VS install location is typically C:\Program Files (x86)\Microsoft Visual Studio\Preview\\*EDITION* where **EDITION** is Community, Enterprise, etc
+If you have an authenticating proxy, you can add your user and password as follows:
 
-How you do this will vary based on your firewall software, but you can find information about [configuring the Windows Firewall here](https://docs.microsoft.com/en-us/windows/security/identity-protection/windows-firewall/create-an-inbound-program-or-service-rule).
+`HTTPS_PROXY=https://user:password@proxy-ip-address:proxyport`
 
 ## See also
 

docs/troubleshooting.md

@@ -51,6 +51,7 @@ The following are troubleshooting tips for sign in problems.
 | All | You are getting a <strong>timeout or connection error</strong>. | See [connectivity troubleshooting](#connectivity). |
 | All | You signed up and were accepted into the preview using an <strong>email address not tied to a Microsoft work, school, or personal account or GitHub account</strong>. | A simple resolution is to add this email address as a secondary email to your GitHub account and sign in that way. VS Live Share simply validates that an accepted email is in your profile when you sign in with GitHub. (Note: Use Tools > Options > Live Share > User account to sign in via GitHub from Visual Studio.) <br /><br /> If that won't work, send a mail to [vsls-feedback@microsoft.com](mailto:vsls-feedback@microsoft.com) and we will switch out your email address.<br /><br />If you have not signed up, you can do so [here](https://aka.ms/vsls-signup) and we will let you know when you've been accepted. |
 | All | When signing in using a Microsoft backed **work or school email address** you see a message saying, **"Need admin approval"**. | Your Azure AD tenet is setup to require “admin consent” for new applications accessing the contents of the directory. Your AD admin would need to resolve this for you but it would only need to be done once for anyone using Live Share. See [here](https://stackoverflow.com/questions/39861830/azure-ad-admin-consent-from-the-azure-portal) and [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-scopes#admin-restricted-scopes).<br /><br /><ul><li>Application Name: Visual Studio Live Share (Insiders)</li><li>Application Type: Web App</li><li>Applications Status: Production</li><li>Delegated Permissions: User.Read</li><li>Application URL: https://insiders.liveshare.vsengsaas.visualstudio.com/</li><li>Reply URL: https://insiders.liveshare.vsengsaas.visualstudio.com/auth/redirect/windowslive/</li></ul><br /> If this is not possible, contact vsls-feedback@microsoft.com and ask to switch to a personal Microsoft account or a GitHub account instead. |
+| VS Code (**macOS**) | When signing in you see an error stating **SecKeychainAddGenericPassword() failed**. | This is almost always due to a common problem with macOS where password changes are not reflected in the login keychain. Try going into "Keychain Access", locking the login keychain and then unlocking it again. This may be enough to resolve the problem, but if you are unable to unlock it with your current password, try your previous one. If that works, change the login keychain password to your current password. See [here](https://support.apple.com/en-us/HT201609) for details. |
 | VS Code (**Linux**) | You are <strong>prompted to enter a user code</strong> but no browser appears to allow you to get one. | We are working to eliminate the user code requirement on Linux. In the mean time, a browser window should appear for you to use to sign in. If not, the browser window may be hidden under VS Code. See the next tip if this is not the case.  |
 | VS Code | After clicking "Sign in" (or using the "Live Share: Sign in" command), <strong>no browser window appears to allow you to enter your credentials</strong>. | 1. Sign in at https://insiders.liveshare.vsengsaas.visualstudio.com/auth/login<br />2. After signing in, click "Having trouble?"<br /> 3. Follow the directions to enter a temporary user code into the tool.<br /><br />Please also run the "Live Share: Export Logs" command and include the zip and a comment on [this bug](https://github.com/MicrosoftDocs/live-share/issues/89). |
 

docs/use/vscode.md

@@ -96,6 +96,8 @@ Visual Studio Live Share uses the .NET Core runtime which requires a number of l
 - libicu52 (for Ubuntu 14.X)
 - libicu55 (for Ubuntu 16.X)
 - libicu57 (for Ubuntu 17.X)
+- gettext
+- apt-transport-https
 
 In addition, the following are libraries **Live Share itself depends on** that may be missing in some instances (e.g. distributions not using Gnome):
 
@@ -104,7 +106,7 @@ In addition, the following are libraries **Live Share itself depends on** that m
 
 Libraries may be installed on Debian/Ubuntu based distributions by running `sudo apt install <library-name>` in a terminal. For example, this will install everything for Ubuntu/Xubuntu/Kubuntu 16.04 or Mint 18.3:
 
-    sudo apt install libunwind8 liblttng-ust0 libcurl3 libssl1.0.0 libuuid1 libkrb5-3 zlib1g gnome-keyring desktop-file-utils libicu55
+    sudo apt install libunwind8 liblttng-ust0 libcurl3 libssl1.0.0 libuuid1 libkrb5-3 zlib1g gnome-keyring desktop-file-utils gettext apt-transport-https libicu55
 
 You will need to replace the last library (libicu55) with the appropriate version for your distribution (e.g. libicu57 for Ubuntu 17.10).