Skip to content

Commit

Permalink
removed the RDS role, application server role and file storage servic…
Browse files Browse the repository at this point in the history
…e prerequisites

removed the creation of an rdp user ("Myrtille") on install (it was used for tests but is no longer relevant)
removed the configuration on the localhost rdp server
added automatic configuration of the firewall (websockets ports)
updated readme and documentation
  • Loading branch information
cedrozor committed Jul 3, 2016
1 parent 92c2b53 commit afbd7f1
Show file tree
Hide file tree
Showing 10 changed files with 609 additions and 132 deletions.
8 changes: 7 additions & 1 deletion CHANGELOG
Original file line number Diff line number Diff line change
@@ -1,4 +1,10 @@
2016-06-11 Version 1.0.4 (beta)
2016-07-03 Version 1.0.5 (stable)
removed the RDS role, application server role and file storage service prerequisites
removed the creation of an rdp user ("Myrtille") on install (it was used for tests but is no longer relevant)
removed the configuration on the localhost rdp server
added automatic configuration of the firewall (websockets ports)

2016-06-11 Version 1.0.4 (beta)
Added domain support to file transfer (see file transfer configuration in documentation)
Build set back to AnyCPU to have 64 bits registry hives loaded on 64 bits machines (fix a load user profile issue)

Expand Down
40 changes: 17 additions & 23 deletions DOCUMENTATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,9 @@ I hope you will enjoy Myrtille! :)
Special thanks to Catalin Trifanescu for its support.

## Prerequisites
Ensure the following Windows Server Roles and Features are installed on the machine on which you want to install Myrtille:
- Remote Destop Services role (formerly Terminal Services). Myrtille only requires the Remote Desktop Session Host. You can either setup it manually (see notes and limitations below) or double click the Myrtille "RDPSetup.reg" file for automatic configuration (import registry keys).
- Web Server role (IIS). Myrtille also requires .NET 4.0, which can be installed separately (using the Myrtille setup bootstrapper or a standalone installation package) or as a IIS feature.
- Applications Server role. Myrtille requires the Windows Processes activation service support, through HTTP, TCP and named pipes.
- Files Storage Service role. Should be installed automatically if the above roles are installed. Myrtille requires the files server feature in order to allow to upload/download file(s) to the connected users documents folders.
- IIS 7.0+ (Web Server role on Windows Servers)
- .NET 4.0+ (Web Server role > Applications Development > ASP.NET 4.5 on Windows Server 2012; can also be installed separately using a standalone .NET 4.x installer)
- Microsoft Visual C++ 2015 redistributables. **CAUTION ** on Windows Server 2012, it requires the system to be fully updated (Windows updates) first; see notes and limitations

## File transfer
Myrtille supports both local and network file storage. If you want your domain users to have access to their documents whatever the connected server, follow these steps:
Expand All @@ -34,31 +32,31 @@ Myrtille supports both local and network file storage. If you want your domain u
- In the settings tab, ensure the user doesn't have exclusive rights to the documents folder (otherwise Myrtille won't be able to access it)

## Network
Add the following rules to the machine firewall:
- "Myrtille Websockets": allow both directions TCP port 8181
- "Myrtille Websockets Secured": allow both directions TCP port 8431
The installer adds the following rules to the machine firewall:
- "Myrtille Websockets": allow both directions TCP port 8181 (default)
- "Myrtille Websockets Secured": allow both directions TCP port 8431 (default)

## Installation
First ensure the prerequisites are met (see above).

All releases here: https://github.com/cedrozor/myrtille/releases
- Setup.exe (preferred installation method): setup bootstrapper; automatically download and install .NET 4.0 and Microsoft Visual C++ 2015 (x86) redistributables (if not already installed), then install the Myrtille MSI package
- Setup.exe (preferred installation method): setup bootstrapper; automatically download and install .NET 4.0 and Microsoft Visual C++ 2015 redistributables (if not already installed), then install the Myrtille MSI package
- Myrtille.msi: Myrtille MSI package (x86)

If you have several RDP servers, you don't have to install Myrtille on each of them; you only have to configure them to be accessed by a Myrtille installation.

You can either do it manually (see notes and limitations below) or copy and import the Myrtille "RDPSetup.reg" file over the servers.

## Security
If you want to use Myrtille through HTTPS (https://yourserver/myrtille), you have to create a self-signed SSL certificate or import a valid one (server side). Then, in order to use secure websockets (WSS), export this certificate into the Myrtille "ssl" folder, with private key, name "PKCS12Cert.pfx" and set a password that match the one defined into the Myrtille "Web.Config" file ("myrtille" by default).

If not using Google Chrome (client side), see detailed comments regarding the security configuration into the Myrtille "Web.Config" file. You may have to add an exception for port 8431 (secure websockets) into your browser.
If not using Google Chrome (client side), see detailed comments regarding the security configuration into the Myrtille "Web.Config" file. You may have to add an exception for the secured websockets port (default 8431) into your browser.

In case of issues, ensure the port 8431 is not blocked by your firewall (or proxy, reverse proxy, VPN, etc.).
In case of issues, ensure the secured websockets port (default 8431) is not blocked by your firewall (or proxy, reverse proxy, VPN, etc.).

## Configuration
Both the gateway and services have their own .NET config files; the gateway also uses XDT transform files to adapt the settings depending on the current solution configuration.

You may also play with the gateway "js/config.js" file settings to fine tune the configuration depending on your needs.

Regarding the RDP server(s) configuration, Myrtille requires NLA to be disabled (see notes and limitations below). You can either do it manually or copy and import the Myrtille "RDPSetup.reg" file over the server(s).

## Code organization
- Myrtille.RDP: C++ code. FreeRDP rdp client; modified to forward the user input(s) and encode the session display into the configured image format(s). The modified code in FreeRDP is identified by region tags "#pragma region Myrtille" and "#pragma endregion".
- Myrtille.Common: C# code. Fleck Websockets library and common helpers.
Expand Down Expand Up @@ -112,7 +110,7 @@ This is a thing to consider if you want to isolate the web gateway from your int
## Notes and limitations
- On Windows Server 2008, you may have to install (manually) the Microsoft Visual C++ 2008 redistributables, required by OpenSSL (libeay32.dll/ssleay32.dll).

- On Windows Server 2012, you may have issues installing the Microsoft Visual C++ 2015 redistributables (http://stackoverflow.com/questions/31536606/while-installing-vc-redist-x64-exe-getting-error-failed-to-configure-per-machi). To circumvent that, ensure your system is fully updated or try to install the package "Windows8.1-KB2999226-x64.msu" manually.
- On Windows Server 2012, you may have issues installing the Microsoft Visual C++ 2015 redistributables (http://stackoverflow.com/questions/31536606/while-installing-vc-redist-x64-exe-getting-error-failed-to-configure-per-machi). To circumvent that, ensure your system is fully updated (Windows updates) first or try to install the package "Windows8.1-KB2999226-x64.msu" manually.

- Myrtille doesn't support clipboard and printer; they could however be enabled through FreeRDP virtual channels, given some additionnal code.

Expand All @@ -122,10 +120,6 @@ This is a thing to consider if you want to isolate the web gateway from your int

- In order to keep the installation simple, both the myrtille gateway and services are installed on the same machine. They do however conform to a distributed architecture; if needed, given some additionnal code, myrtille services could acts as a proxy, so the gateway could be installed and operate separately (this could be handy if the gateway should go into a DMZ).

- The installer creates a test user on the local machine named "myrtille", password "/Passw1rd/"; feel free to remove it if unwanted. The user is automatically removed on uninstall.

- The installer configures the RDP server on the local machine according to the Myrtille specifications (see above comment regarding NLA); any subsequent configuration changes may make Myrtille to dysfunction or stop working.

## Troubleshoot
First at all, ensure the Myrtille prerequisites are met (see "Prerequisites").

Expand All @@ -142,11 +136,11 @@ First at all, ensure the Myrtille prerequisites are met (see "Prerequisites").
- Ensure the network traffic (websockets and xmlhttp in particular) is not blocked by a firewall, proxy, reverse proxy, VPN or whatever.
- Ensure IIS is started and "Myrtille.Web" application is running on the "MyrtilleAppPool" application pool.
- Ensure .NET 4.0 is installed and the "MyrtilleAppPool" is running on it.
- If using HTTPS with HTML5 rendering (hence secure websockets, WSS), ensure the TCP port 8431 is opened (see "Security").
- If using HTTPS with HTML5 rendering (hence secure websockets, WSS), ensure the secured websockets port (default 8431) is opened (see "Security").
- Ensure the "Myrtille.Services" Windows service (or console application if running under Visual Studio) is started.
- Ensure the RDP client ("FreeRDP.wfreerdp.exe") does exists (into the "Myrtille.Services" output folder, if running under Visual Studio, or into the "bin" folder otherwise); if not, you need to build the "Myrtille.RDP/FreeRDP.wfreerdp" project (or simply build all the solution).
- Ensure the Microsoft Visual C++ 2015 (x86) redistributables are installed (and also Microsoft Visual C++ 2008 (x86) redistributables if on Windows Server 2008); they are required by the RDP client.
- Check the RDP server configuration (**ensure NLA is disabled** (Myrtille supports standard RDP authentication only; see notes and limitations), does the user exists, is it a member of the "Remote Desktop Users" group, are Remote Desktop CALs valid?, etc.).
- Ensure the Microsoft Visual C++ 2015 redistributables are installed (and also Microsoft Visual C++ 2008 redistributables if on Windows Server 2008); they are required by the RDP client.
- Check the RDP server configuration (**ensure NLA is disabled** (Myrtille supports standard RDP authentication only; see notes and limitations), does the user exists, is it a member of the "Remote Desktop Users" group, are Remote Desktop CALs valid?, etc.). You can setup it automatically by importing the Myrtille "RDPSetup.reg" file into registry.
- Check the RDP server logs (and also the Windows events logs on the RDP server machine).
- Check the Windows events logs ("System", "Application", etc.), particulary regarding .NET.
- Retry with Myrtille logs enabled and check them (Myrtille "log" folder). You can change their verbosity level in config (but be warned it will affect peformance and flood the disk if setted too verbose).
Expand Down
60 changes: 60 additions & 0 deletions Myrtille.Common/Helpers/FirewallHelper.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
using System;
using System.Diagnostics;
using NetFwTypeLib;

namespace Myrtille.Helpers
{
public static class FirewallHelper
{
public static void OpenFirewallPort(int port, string description)
{
try
{
// firewall manager
var TicfMgr = Type.GetTypeFromProgID("HNetCfg.FwMgr");
var icfMgr = (INetFwMgr)Activator.CreateInstance(TicfMgr);

// open port
var TportClass = Type.GetTypeFromProgID("HNetCfg.FWOpenPort");
var portClass = (INetFwOpenPort)Activator.CreateInstance(TportClass);

// current profile
var profile = icfMgr.LocalPolicy.CurrentProfile;

// set properties
portClass.Scope = NET_FW_SCOPE_.NET_FW_SCOPE_ALL;
portClass.Protocol = NET_FW_IP_PROTOCOL_.NET_FW_IP_PROTOCOL_TCP;
portClass.Port = port;
portClass.Name = description;
portClass.Enabled = true;

// add the port to the ICF permissions list
profile.GloballyOpenPorts.Add(portClass);
}
catch (Exception exc)
{
Trace.TraceError("Failed to open firewall port ({0})", exc);
}
}

public static void CloseFirewallPort(int port)
{
try
{
// firewall manager
var TicfMgr = Type.GetTypeFromProgID("HNetCfg.FwMgr");
var icfMgr = (INetFwMgr)Activator.CreateInstance(TicfMgr);

// current profile
var profile = icfMgr.LocalPolicy.CurrentProfile;

// add the port to the ICF permissions list
profile.GloballyOpenPorts.Remove(port, NET_FW_IP_PROTOCOL_.NET_FW_IP_PROTOCOL_TCP);
}
catch (Exception exc)
{
Trace.TraceError("Failed to remove firewall port ({0})", exc);
}
}
}
}
114 changes: 114 additions & 0 deletions Myrtille.Common/Helpers/XmlTools.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
using System.Xml;
using System.Xml.XPath;

namespace Myrtille.Helpers
{
public static class XmlTools
{
public static XmlNode GetNode(
XmlNode parentNode,
string name)
{
XmlNode theNode = null;

if ((parentNode != null) &&
(parentNode.ChildNodes != null) &&
(parentNode.ChildNodes.Count > 0))
{
foreach (XmlNode node in parentNode.ChildNodes)
{
if (node.Name.ToUpper().Equals(name.ToUpper()))
{
theNode = node;
break;
}
}
}

return theNode;
}

public static XmlNode GetNode(
XPathNavigator navigator,
string path)
{
XmlNode node = null;

var iterator = navigator.Select(path);
if (iterator.Count == 1)
{
iterator.MoveNext();
node = ((IHasXmlNode)iterator.Current).GetNode();
}

return node;
}

public static string ReadConfigKey(
XmlNode parentNode,
string key)
{
if ((parentNode != null) &&
(parentNode.ChildNodes != null) &&
(parentNode.ChildNodes.Count > 0))
{
XmlNode theNode = null;

foreach (XmlNode node in parentNode.ChildNodes)
{
if ((node.Name.ToUpper().Equals("ADD")) &&
(node.Attributes != null) &&
(node.Attributes["key"] != null) &&
(node.Attributes["key"].Value.ToUpper().Equals(key.ToUpper())))
{
theNode = node;
break;
}
}

if ((theNode != null) &&
(theNode.Attributes != null) &&
(theNode.Attributes["value"] != null))
{
var theNodeValue = theNode.Attributes["value"];
return theNodeValue.Value;
}
}

return null;
}

public static void WriteConfigKey(
XmlNode parentNode,
string key,
string value)
{
if ((parentNode != null) &&
(parentNode.ChildNodes != null) &&
(parentNode.ChildNodes.Count > 0))
{
XmlNode theNode = null;

foreach (XmlNode node in parentNode.ChildNodes)
{
if ((node.Name.ToUpper().Equals("ADD")) &&
(node.Attributes != null) &&
(node.Attributes["key"] != null) &&
(node.Attributes["key"].Value.ToUpper().Equals(key.ToUpper())))
{
theNode = node;
break;
}
}

if ((theNode != null) &&
(theNode.Attributes != null) &&
(theNode.Attributes["value"] != null))
{
var theNodeValue = theNode.Attributes["value"];
theNodeValue.Value = value;
}
}
}
}
}
13 changes: 13 additions & 0 deletions Myrtille.Common/Myrtille.Common.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -103,10 +103,12 @@
<SubType>Code</SubType>
</Compile>
<Compile Include="Helpers\FileHelper.cs" />
<Compile Include="Helpers\FirewallHelper.cs" />
<Compile Include="Helpers\IISHelper.cs" />
<Compile Include="Helpers\PermissionsHelper.cs" />
<Compile Include="Helpers\PipeHelper.cs" />
<Compile Include="Helpers\WindowHelper.cs" />
<Compile Include="Helpers\XmlTools.cs" />
<Compile Include="Log\Log4netTraceFilter.cs" />
<Compile Include="Log\Log4netTraceListener.cs" />
<Compile Include="Properties\AssemblyInfo.cs" />
Expand Down Expand Up @@ -154,6 +156,17 @@
<None Include="Fleck\readme.markdown" />
<None Include="Fleck\VERSION" />
</ItemGroup>
<ItemGroup>
<COMReference Include="NetFwTypeLib">
<Guid>{58FBCF7C-E7A9-467C-80B3-FC65E8FCCA08}</Guid>
<VersionMajor>1</VersionMajor>
<VersionMinor>0</VersionMinor>
<Lcid>0</Lcid>
<WrapperTool>tlbimp</WrapperTool>
<Isolated>False</Isolated>
<EmbedInteropTypes>True</EmbedInteropTypes>
</COMReference>
</ItemGroup>
<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
<PropertyGroup>
<PostBuildEvent>
Expand Down
Loading

0 comments on commit afbd7f1

Please sign in to comment.