Getting familiar with Microsoft Tunnel Gateway

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.

DirectoryDirectory description
/etc/mstunnelThis is the root directory that contains the configuration.
/etc/mstunnel/certsThis is the directory that contains the TLS certificate.
/etc/mstunnel/privateThis 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.

FileFile description
AgentSettings.jsonThis file contains the generic server configuration information (name, site, and more).
admin-settings.jsonThis file contains the configuration as configured in the Server configuration in Intune.
agent-info.jsonThis file contains the agent information (Intune tenant Id, Azure AD tenant Id, and more).
Images_configuredThis file contains the hash values of the current images.
ocserv-sec.jsonThis file contains the VPN server configuration information.
ocserv.confThis file contains the VPN server configuration.
oidc.jsonThis file contains the OpenID configuration.
version-info.jsonThis file contains the version information (configuration version, docker version, and more).
env.shThis 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 = 15000

oidc.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.

IdentifierIdentifier description
ocservThis identifier only displays the VPN server logs.
mstunnel-agentThis identifier only displays the Intune agent logs.
mstunnel_monitorThis 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

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.

CommandCommand description
agentOperate commands on the agent component (use the -h command for more command options).
serverOperate commands on the server component (use the -h command for more command options).
uninstallUninstall Microsoft Tunnel Gateway.
eulaShow the EULA that was accepted during the installation of Microsoft Tunnel Gateway.
import_certImport 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

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.

CommandCommand description
statusShows the status of the agent component.
startStart the service of the agent component.
stopStop the service of the agent component.
restartRestart 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

server parameter

When looking at the server command, the following commands are options for interacting with the server component.

CommandCommand description
statusShows the status of the server component.
startStart the service of the server component.
stopStop the service of the server component.
restartRestart the service of the server component.
showShow 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

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”

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.