This week is a follow-up on my post of a few weeks ago about getting started with Microsoft Tunnel Gateway. In that post I’ve showed how to get started with Microsoft Tunnel Gateway and in this post I want to show how to get more familiar with Microsoft Tunnel Gateway. Getting to know the installation location, getting to know the configuration files, getting to know the log files and getting to know a few important commands for more information. All of that will eventually help with getting more familiar with Microsoft Tunnel Gateway. In this post I’ll look a few directories, files, logs and commands. Also in that order.
Directories
Let’s start with a few directories. Actually, one directory and a few sub-directories. After the installation of Microsoft Tunnel Gateway, a few important directories become available. Below are the most important directories, including a short description.
| Directory | Directory description |
|---|---|
| /etc/mstunnel | This is the root directory that contains the configuration. |
| /etc/mstunnel/certs | This is the directory that contains the TLS certificate. |
| /etc/mstunnel/private | This is the directory that contains the Intune Agent certificate and the TLS private key. |
Tip: When navigating to the root directory, a simple ls command will show all the available directories. Keep in mind that the permissions will be denied for a normal user and that the usage of sudo is required.
Files
Within the mentioned root directory, many files are added during the different stages of the installation of Microsoft Tunnel Gateway. Below are the most important files, including a short description and an example.
| File | File description |
|---|---|
| AgentSettings.json | This file contains the generic server configuration information (name, site, and more). |
| admin-settings.json | This file contains the configuration as configured in the Server configuration in Intune. |
| agent-info.json | This file contains the agent information (Intune tenant Id, Azure AD tenant Id, and more). |
| Images_configured | This file contains the hash values of the current images. |
| ocserv-sec.json | This file contains the VPN server configuration information. |
| ocserv.conf | This file contains the VPN server configuration. |
| oidc.json | This file contains the OpenID configuration. |
| version-info.json | This file contains the version information (configuration version, docker version, and more). |
| env.sh | This file contains the environment variables (like the proxy addresses) when used. |
Tip: When looking at the files in the directory, a simple cat command will print the content in the terminal. Keep in mind that the permissions will be denied for a normal user and that the usage of sudo is required.
Note: AgentLoggingInfo.json, AgentMonitorLoggingInfo.json, GeneralLoggingInfo.json, JournalLoggingInfo.json, OcservErrorLoggingInfo.json, OcservLoggingInfo.json and VpnLoggingInfo.json only contain the last processed logs date and mstunnel-agent-state and mstunnel-server-state only contains the status of the service.
AgentSetting.json
The AgentSettings.json shows the generic server properties. That includes the id of the site that the server belongs to, the name of the server, the id of the server and the id of the configurations that is applied to the server. Below is an example of an AgentSettings.json file.
{
"SiteId":"n0tm1n3-da01-4633-9ad4-82bf34a93ab4",
"ServerName":"cldmtg01",
"ServerId":"n0tm1n3-3d69-4d8f-bdc0-e0c0e929bb6c",
"ConfigId":"n0tm1n3-5c3c-43a9-8324-deb553da795b",
"ServerImageTime":"2020-10-13T20:18:26.2199173+00:00",
"AgentImageTime":"2020-10-13T20:18:26.1972649+00:00",
"PatchExpirationDate":"0001-01-01T00:00:00+00:00"
}admin-settings.json
The admin-settings.json shows the configured properties of the Server configuration. This file should only be adjusted by using Intune and not manually. Below is an example of an agent-settings.json file.
{
"DisplayName": "Default server configuration",
"Network": "192.168.50.1/24",
"DNSServers": [
"192.168.20.1"
],
"DefaultDomainSuffix": "",
"RoutesInclude": [],
"RoutesExclude": [],
"ListenPort": 443,
"ConfigVersion": 637370578342241628,
"SplitDNS": [],
"AditionalSettings": []
}agent-info.json
The agent-info.json shows the basic agent properties. That includes the id of the agent, the id of the Intune tenant that the server belongs to, the id of the Azure AD tenant that the server belongs to and the certificate information. Below is an example of an agent-info.json file.
{
"AgentId": "n0tm1n3-09ff-4e0b-8c0b-0e1b7d6cb5fb",
"IntuneTenantId": "n0tm1n3-8b8f-428c-a3f6-774ec1f94b6d",
"AADTenantId": "n0tm1n3-1ce1-41db-8aff-4c59298d4ba9",
"Type": 8,
"Certificate": null,
"RenewalDate": "2021-08-20T10:34:01+00:00"
}Images_configured
The Images_configured show the hash values of the installed images. That information can be used to identify the version of the installed images. Below is an example of an Images_configured file.
mst_use_custom_image=""
agentImageDigest="sha256:3d888864ecafa1d8c05754e3059519a2cf0d4ca56a234e13f60431cff9ba152b"
serverImageDigest="sha256:525f329010088bd4a27e930e613635dc3cbcadd0611011c6d5d8f5e1d087cb41"ocserv-sec.json
The ocserv-sec.json shows the VPN server properties. That includes the authentication configuration that is used and the certificate configuration that is used. Below is an example of an ocserv-sec.json file.
{
"StatsReportTime": 60,
"StatsResetTime": 3600,
"MaxClients": 5500,
"RateLimit": 100,
"KeepAlive": 32400,
"AuthTimeout": 40,
"MinReauthTime": 300,
"Auth": "oidc[config=/etc/ocserv/oidc.json]",
"CertPath": "/etc/ocserv/certs/site.crt",
"KeyPath": "/etc/ocserv/private/site.key",
"PinPath": null,
"UseOcctl": true,
"Rekey": "ssl",
"PidFile": "/var/run/ocserv.pid",
"SockeFile": "/var/run/ocserv-socket",
"RunAsUser": "nobody",
"RunAsGroup": "nogroup",
"IsolateWorkers": true,
"Device": "ma-tun",
"CookieTimeout": 300,
"PersistentCookies": true,
"MobileDpd": 1800,
"Dpd": 240,
"TryMtuDiscovery": true,
"TlsPriorities": "Secure256:-CIPHER-ALL:\u002BAES-256-GCM:-KX-ALL:\u002BECDHE-RSA:-MAC-ALL:\u002BAEAD:-VERS-TLS-ALL:\u002BVERS-TLS1.3:\u002BVERS-TLS1.2:-COMP-ALL",
"MatchTlsDtlsCiphers": true,
"DtlsLegacy": false,
"ConnectScript": "/usr/local/sbin/ocserv-telemetry.sh",
"DisconnectScript": "/usr/local/sbin/ocserv-telemetry.sh",
"ServerDrainMs": 15000
}ocserv.conf
The ocserv.conf shows the VPN server configuration. That includes the network configuration, the authentication configuration and the certificates that are used. Below is an example of an ocserv.conf file.
ipv4-network = 192.168.50.1/24
dns = 192.168.20.1
route = default
tcp-port = 443
udp-port = 443
server-stats-reset-time = 3600
max-clients = 5500
rate-limit-ms = 100
auth = oidc[config=/etc/ocserv/oidc.json]
server-cert = /etc/ocserv/certs/site.crt
server-key = /etc/ocserv/private/site.key
use-occtl = True
rekey-method = ssl
pid-file = /var/run/ocserv.pid
socket-file = /var/run/ocserv-socket
run-as-user = nobody
run-as-group = nogroup
isolate-workers = True
device = ma-tun
cookie-timeout = 300
persistent-cookies = True
mobile-dpd = 1800
dpd = 240
try-mtu-discovery = True
tls-priorities = Secure256:-CIPHER-ALL:+AES-256-GCM:-KX-ALL:+ECDHE-RSA:-MAC-ALL:+AEAD:-VERS-TLS-ALL:+VERS-TLS1.3:+VERS-TLS1.2:-COMP-ALL
match-tls-dtls-ciphers = True
dtls-legacy = False
connect-script = /usr/local/sbin/ocserv-telemetry.sh
disconnect-script = /usr/local/sbin/ocserv-telemetry.sh
server-drain-ms = 15000oidc.json
The oidc.json shows the OpenID properties. That includes the sts-url that is used and the issuer. Below is an example of the oidc.json file.
{
"openid_configuration_url": "https://sts.windows.net/n0tm1n3-1ce1-41db-8aff-4c59298d4ba9/v2.0/.well-known/openid-configuration",
"user_name_claim": "oid",
"required_claims": {
"aud": "n0tm1n3-9681-447a-974d-d19f668fcd88",
"acct": 0,
"iss": "https://sts.windows.net/n0tm1n3-1ce1-41db-8aff-4c59298d4ba9/"
}
}version-info.json
The version-info.json shows the version information of the different components. That includes, the version of the configuration, the version of Docker, the version of the different images and the version of the operating system. Below is an example of the version-info.json file.
{
"ConfigVersion": 637370578342241628,
"DockerVersion": "Docker version 19.03.13, build 4484c46d9d",
"AgentImageHash": "sha256:3d888864ecafa1d8c05754e3059519a2cf0d4ca56a234e13f60431cff9ba152b",
"AgentCreateDate": "2020-10-09T18:50:54.560584825Z",
"ServerImageHash": "sha256:525f329010088bd4a27e930e613635dc3cbcadd0611011c6d5d8f5e1d087cb41",
"ServerCreateDate": "2020-10-09T18:49:24.487117764Z",
"HostOS": "Ubuntu 20.04.1 LTS",
"HostKernel":"5.4.0-48-generic"
}Commands
When looking at the different commands that are available for basic interaction with Microsoft Tunnel Gateway, locally on the Linux server, journalctl is important for querying the journal (the place for logs) and mst-cli is important for actually interacting with Microsoft Tunnel Gateway.
Logs
With the latest update of Microsoft Tunnel Gateway, the logs are logged in the Linux server logs in the syslog format. That also means that the standard journalctl command can be used view the journal (the logs) and that the -t parameter can be used for showing entries with only the specific identifier. When looking at the Microsoft Tunnel Gateway log entries, the identifiers in the table below are important.
| Identifier | Identifier description |
|---|---|
| ocserv | This identifier only displays the VPN server logs. |
| mstunnel-agent | This identifier only displays the Intune agent logs. |
| mstunnel_monitor | This identifier only displays the monitoring task logs. |
An example for using journalctl for displaying the Intune agent logs, can be found below.
journalctl -t mstunnel_monitor
Figure 1: Example of the logs command
Tip: When looking at the logs, the -f parameter will follow the log and display a rolling log. For more an overview of all the available parameters, use the -h parameter.
Interface
For local interaction with Microsoft Tunnel Gateway, Microsoft provides the mst-cli command-line tool. This command-line tool is available on the Linux server after the installation of Microsoft Tunnel Gateway and can be found at /usr/sbin/mst-cli. This command-line tool can be used to get some basic interaction with Microsoft Tunnel Gateway, like getting information, restarting the service and server and even uninstalling Microsoft Tunnel Gateway.
Note: Keep in mind that when running the mst-cli command-line tool, the usage of sudo is required.
When looking at the mst-cli command-line tool, the following commands are the first layer of local interaction capabilities with Microsoft Tunnel Gateway.
| Command | Command description |
|---|---|
| agent | Operate commands on the agent component (use the -h command for more command options). |
| server | Operate commands on the server component (use the -h command for more command options). |
| uninstall | Uninstall Microsoft Tunnel Gateway. |
| eula | Show the EULA that was accepted during the installation of Microsoft Tunnel Gateway. |
| import_cert | Import the TLS certificate. |
An example for using mst-cli, can be found below. This example will show the accepted EULA.
sudo /usr/sbin/mst-cli eula
Figure 2: Example of the EULA command
Important: Be careful with the uninstall parameter of the mst-cli command-line tool, because at this moment the uninstall will start immediately without verification.
agent parameter
When looking at the agent command, the following commands are the options for interacting with the agent component.
| Command | Command description |
|---|---|
| status | Shows the status of the agent component. |
| start | Start the service of the agent component. |
| stop | Stop the service of the agent component. |
| restart | Restart the service of the agent component. |
An example for using mst-cli agent, can be found below. This example will show the status of the agent component.
sudo /usr/sbin/mst-cli agent status
Figure 3: Example of the agent command
server parameter
When looking at the server command, the following commands are options for interacting with the server component.
| Command | Command description |
|---|---|
| status | Shows the status of the server component. |
| start | Start the service of the server component. |
| stop | Stop the service of the server component. |
| restart | Restart the service of the server component. |
| show | Show various stats of the server component (use the -h command for more command options). This command can show a lot of stats, including the statistics of the server and the connected users. |
An example for using mst-cli server, can be found below. This example will show the status of the server component.
sudo /usr/sbin/mst-cli server status
Figure 4: Example of the server command
Tip: For an overview of all the available commands use sudo /usr/sbin/mst-cli -h. For an overview of the available commands for a specific component use something similar to sudo /usr/sbin/mst-cli server show -h.
More information
For more information about the further details about Microsoft Tunnel Gateway, refer to the following docs.
2 thoughts on “Getting familiar with Microsoft Tunnel Gateway”