In order to connect a device to macchina.io REMOTE, a program (macchina.io REMOTE Device Agent
or WebTunnelAgent) needs to be installed on the device. For initial testing, the agent can also be
installed on a Windows, Linux or macOS machine in the same network as the device.
WebTunnelAgent is built as part of the macchina.io REMOTE SDK.
WebTunnelAgent needs a configuration file named WebTunnelAgent.properties to work.
The easiest way to obtain the configuration file is to generate and download it from the
macchina.io REMOTE Account page. A basic configuration file
is also available in this directory.
The configuration file should be located in the same directory as WebTunnelAgent.
Alternatively, the path to the configuration file can be specified when starting
WebTunnelAgent using the --config-file option:
WebTunnelAgent --config=/path/to/WebTunnelAgent.properties
Note that on Windows the command-line parameters must be given Windows-style:
WebTunnelAgent /config=c:\\path\to\WebTunnelAgent.properties
In some environments it may be required to connect to the macchina.io REMOTE server
via a HTTP proxy. This can be done by providing the address of the proxy server
on in the configuration file, using the http.proxy.host and http.proxy.port
settings, or alternatively combining both in http.proxy.url.
Proxy credentials can be specified with http.proxy.username and http.proxy.password.
See the configuration section for more information.
On Linux and macOS systems, WebTunnelAgent can be run as a daemon.
To do so, pass the --daemon option:
WebTunnelAgent --daemon
Additional options can be passed to set the daemon's umask, or create a pidfile. Please run
WebTunnelAgent --help
for more information.
A Debian-style Linux init script for /etc/init.d/ is included
with the source code. It expects the WebTunnelAgent executable to be located in
/usr/local/sbin/WebTunnelAgent and the configuration file in /etc/WebTunnelAgent.properties.
Copy the init script to /etc/init.d/ and make it executable. Copy the
WebTunnelAgent executable to /usr/local/sbin/ and make sure it's executable as well.
Copy the configuration file WebTunnelAgent.properties to /etc/.
Then enable the startup script with:
sudo /usr/sbin/update-rc.d WebTunnelAgent defaults
sudo /usr/sbin/update-rc.d WebTunnelAgent enable
and start with:
sudo /etc/init.d/WebTunnelAgent start
A systemd service file is available in
etc/systemd/system/WebTunnelAgent.service.
The file must be copied to the target system to /etc/systemd/system/WebTunnelAgent.service.
Like the init.d script, it expects the WebTunnelAgent executable to be located in
/usr/local/sbin/WebTunnelAgent and the configuration file in /etc/WebTunnelAgent.properties.
To start the service and make it run automatically at startup:
sudo systemctl daemon-reload
sudo systemctl start WebTunnelAgent
sudo systemctl enable WebTunnelAgent
WebTunnelAgent can be registered as a service on Windows.
To do so, start it with the /registerService option.
This must be done from a Command Prompt with Administrator privileges.
WebTunnelAgent /registerService
Additional options such as /displayName, /description and /startup
can also be used to specify service properties.
Please run
WebTunnelAgent /help
for more information.
The WebTunnelAgent service can be started from the Services MMC plugin, or via
the command-line:
net start WebTunnelAgent
To stop the WebTunnelAgent service, run:
net stop WebTunnelAgent
To unregister the WebTunnelAgent service, run:
WebTunnelAgent /unregisterService
WebTunnelAgent is configured using a configuration file usually named
WebTunnelAgent.properties. If the file is located in the same directory
as the WebTunnelAgent executable, or a parent directory, it will be picked up
automatically. Otherwise, the path to the configuration file can be specified using
the --config-file or /config-file command-line parameter.
The configuration file can be edited with any text editor. It
contains a number of settings that control various aspects of the
WebTunnelAgent. For better readability, the configuration
file is divided into different sections. The sections and settings
are described in the following.
The configuration file format is as follows. A line starting with a hash '#' or exclamation mark '!' is treated as a comment and is ignored. Every other line denotes a setting definition in the form
key = value
or
key: value
Keys and values may contain special characters represented by the following escape sequences:
\t: tab (0x09)\n: line feed (0x0a)\r: carriage return (0x0d)\f: form feed (0x0c)
For every other sequence that starts with a backslash, the backslash is removed.
Therefore, the sequence \a would just yield an 'a'.
A value can spread across multiple lines if the last character in a line
(the character immediately before the carriage return or line feed character) is a
single backslash. Setting keys are case sensitive. Leading and trailing whitespace is
removed from both keys and values. A setting name can neither contain a colon ':'
nor an equal sign '=' character.
In a value it’s possible to reference another value using the syntax ${key}.
There are a number of system settings that can be used as well:
system.osName: the operating system namesystem.osVersion: the operating system versionsystem.osArchitecture: the operating system architecturesystem.nodeName: the node (or host) namesystem.nodeId: system ID, based on the Ethernet address (format"xxxxxxxxxxxx") of the first Ethernet adapter found on the systemsystem.currentDir: the current working directorysystem.homeDir: the user's home directorysystem.tempDir: the system's temporary directorysystem.dateTime: the current UTC date and time, formatted in ISO 8601 format (example:2005-01-01T11:00:00Z)system.pid: the current process IDsystem.env.NAME: the value of the environment variable with the given NAMEapplication.path: the absolute path to theWebTunnelAgentexecutableapplication.name: the name of theWebTunnelAgentexecutableapplication.dir: the path to the directory containing theWebTunnelAgentexecutable
Settings not recognized by WebTunnelAgent will be ignored. However, it is still
possible to reference these setting’s values in other settings.
This can be used to introduce "macro" settings which are referenced in multiple settings.
It is also possible to specify a default value when referencing a different setting. This
will be used if the referenced value is not defined. The format is ${key:-<default>},
where <default> is the default value.
This setting specifies the domain UUID which is used to associate the device with a user account
or user group. It can also be used to group devices. The value should be an all lower-case
UUID like d5f6e710-49c9-4e21-9cd7-2ae0054c3f13. How domains are assigned to devices
and users depends on the specific macchina.io REMOTE server instance. For example, the
public test server assigns a unique domain UUID to
each new registered user account.
Please note that it's not allowed to change the domain UUID of an already registered device unless device authentication has been enabled.
The device ID is used to uniquely address the device and therefore must be unique
for all devices on a macchina.io REMOTE server.
The ID must be a valid domain name, as it will be used as part of the device URL.
It may contain letters a-z and digits 0-9, as well as dashes (-),
but must not begin with a dash.
It's possible to use the system's Ethernet address (${system.nodeId}) as ID
or part of the ID. However, please note that on some systems the Ethernet address
reported by ${system.nodeId} may change between reboots if the system has
multiple network adapters.
This optional property can be used to set the device name property shown in the
macchina.io REMOTE dashboard and device page.
Note that if enabled, this will set the name property of the device only once,
when the device is created on the server when the initial connection is made.
Further changes to the device name have to be made directly on the macchina.io REMOTE
web interface, or through its API.
You can specify a name, or use a configuration variable like
${system.nodeName} or refer to an environment variable like
${system.env.HOSTNAME}.
This optional property can be used to set the device version property shown
in the macchina.io REMOTE device page (and optionally dashboard, if configured).
It's intended to report the device's firmware version number or something equivalent.
Note that if enabled, this will cause the device version property to be
set every time WebTunnelAgent connects to the macchina.io REMOTE, therefore
overwriting any changes made in the macchina.io REMOTE web interface, shell
or API.
This optional property can be used to set the device userAgent property
shown in the macchina.io REMOTE device page.
This setting specifies the IP address or domain name of the target device.
If WebTunnelAgent is running directly on the target device, this can be
the loopback address 127.0.0.1.
This setting specifies a comma-separated list of port numbers to forward. It should include the port number of the device's web server (usually 80, but can be another one). Can also include SSH (22), VNC (5900) or other TCP ports.
This setting specifies the port number of the device's web server. Must only be
set if different from default HTTP port 80. Must also be included in the webtunnel.ports list.
If the device has only a HTTPS server, specify the port of the server here and set
the webtunnel.https.enable property to true.
Set this property to true if the device only has a HTTPS server. In this case,
WebTunnelAgent will connect to the designated device HTTP server port
(webtunnel.httpPort) over TLS.
This optional setting specifies the default URI path of the device's web server. It will be used by the macchina.io REMOTE web user interface to construct the URL of the device.
The optional setting specifies the port number of the device's SSH server.
Used to enable SSH support in the macchina.io REMOTE web interface.
The port number must also be included in the webtunnel.ports list.
If not set SSH access will not be enabled via the macchina.io REMOTE web interface.
The optional setting specifies the port number of the device's VNC server.
Used to enable VNC support in the macchina.io REMOTE web interface.
The port number must also be included in the webtunnel.ports list.
If not set VNC access will not be enabled via the macchina.io REMOTE web interface.
This optional setting specifies the port number of the device's RDP server.
Used to enable RDP support in the macchina.io REMOTE web interface.
The port number must also be included in the webtunnel.ports list.
If not set RDP access will not be enabled via the macchina.io REMOTE web interface.
This optional setting specifies the port number of the device's
application protocol server.
This can be used for tunneling protocols such as Modbus/TCP (502),
OPC-UA (4840) or other custom application protocols.
Used to enable transparent TCP tunneling support in the
macchina.io REMOTE web interface, via macchina.io REMOTE Helper.
The port number must also be included in the webtunnel.ports list.
The URL of the macchina.io REMOTE server.
The username of the device. Always consists of device ID (webtunnel.deviceId) and
the domain UUID (webtunnel.domain), separated by '@'.
Should always be set to:
webtunnel.username = ${webtunnel.deviceId}@${webtunnel.domain}
The device password, used for authenticating the device. Device authentication is disabled on the public demo server, so can be left empty. Device authentication can be enabled for private macchina.io REMOTE instances.
The timeout (given in seconds) for connecting to the local (forwarded) server socket, e.g., the device's web server.
The send and receive timeout (given in seconds) for local (forwarded) socket connections, i.e., the connection to the device's web server.
The timeout (given in seconds) for the WebTunnel connection to the macchina.io REMOTE
server. If half of the timeout expires, the WebTunnelAgent will send a PING message to the
macchina.io REMOTE server. If the PING is not answered by the server, the WebTunnelAgent
will terminate the connection and attempt to re-connect.
This optional setting specifies the path to an executable that is started whenever the state of the tunnel connection to the macchina.io REMOTE changes. The current state will be passed as command-line argument to the executable and will be one of:
connected: the tunnel connection has been established.disconnected: the tunnel connection has been disconnected.error: there has been an error establishing the tunnel. A second parameter will also be passed containing more information about the error.
This setting specifies additional device properties that are sent to the macchina.io REMOTE. Format is:
webtunnel.properties.<property> = <value>
Multiple properties can be specified.
If <value> is enclosed in backticks (`<value>`), then <value> is considered
to be a shell command that is executed to obtain the actual value.
Example:
webtunnel.properties.uptime = `uptime`
Will set the value of the uptime property to the result of running the uptime
command. The command will be executed by the system's shell, so it's also possible
to combine commands with a pipe, e.g.:
webtunnel.properties.cpuLoad = `uptime | awk '{print $10}'`
To send updates to properties to the macchina.io REMOTE server periodically, and not
just when connecting the tunnel, see webtunnel.propertiesUpdateInterval.
This optional setting specifies the interval in seconds in which property
updates are sent to the macchina.io REMOTE server. If set to 0 (default), any
defined properties (see webtunnel.properties) will only be sent when
the agent connects (or reconnects) to the macchina.io REMOTE server.
If set to a non-zero value, property updates will be sent periodically.
The timeout (given in seconds) for the initial HTTP(S) connection to the macchina.io REMOTE server.
Enable (set to true) or disable (set to false) HTTP proxy support for the
HTTP/WebTunnel connection to the macchina.io REMOTE server.
If enabled, the proxy host, port, username and password should also be specified.
The domain name or IP address of the HTTP proxy server to use.
The port number of the HTTP proxy server to use.
An alternative form to specify a HTTP proxy, taking a URL, e.g.:
http.proxy.url = http://proxy.nowhere.com:8080
Note that http.proxy.host and http.proxy.port will take precedence,
if specified.
This can be used if the proxy address is provided via an environment variable,
like https_proxy on Linux:
http.proxy.url = ${system.env.https_proxy}
The username for authenticating against the HTTP proxy server. Can be left empty if no proxy authentication is required.
The password for authenticating against the HTTP proxy server. Can be left empty if no proxy authentication is required.
Enable (true) or disable (false) accepting an unknown certificate from the
macchina.io REMOTE server or the device web server. Should only be used for testing purposes,
e.g., while using a self-signed certificate. Should not be used in production setups.
This setting is used to specify a list of acceptable OpenSSL ciphers. Only used
if WebTunnelAgent has been built with OpenSSL.
This setting is used to specify the minimum TLS version required by WebTunnelAgent
when connecting to the macchina.io REMOTE server. The following values can be
specified:
tlsv1ortlsv1_0(TLS version 1.0)tlsv1_1(TLS version 1.1)tlsv1_2(TLS version 1.2, default)tlsv1_3(TLS version 1.3)
This optional setting specifies the certificate validation mode for the connection to the macchina.io REMOTE server. Use one of the following values.
none: The server certificate is not validated.relaxed: The server certificate is validated if one is presented by the server. This is the default.strict: The server certificate is validated and it is an error if the server does not present a certificate.
Enable (true) or disable (false) extended (domain name) certificate validation.
If set to true, which is highly recommended, WebTunnelAgent will verify that the
common name (or one of the Subject Alternative names) of the server certificate
matches the server domain name, as specified in webtunnel.reflectorURI.
This setting specifies a directory or file containing trusted root certificates for OpenSSL. Can be left empty to use the built-in default OpenSSL root certificates. Please note that OpenSSL on Windows may not include a list of trusted root certificates.
This optional setting specifies the path to an X509 certificate file in PEM format used for authenticating the device against the server (together with a private key, specified using tls.privateKey property).
This optional setting specifies the path to an X509 private key file in PEM format used for authenticating the device against the server (together with a certificate, specified using tls.certificate property).
This setting is used to specify a list of acceptable OpenSSL ciphers for the HTTPS
connection to the device web server. Only used if WebTunnelAgent has been built
with OpenSSL.
This setting is used to specify the minimum TLS version required by WebTunnelAgent
when connecting to the device web server via HTTPS. The following values can be
specified:
tlsv1ortlsv1_0(TLS version 1.0)tlsv1_1(TLS version 1.1)tlsv1_2(TLS version 1.2, default)tlsv1_3(TLS version 1.3)
This optional setting specifies the certificate validation mode for the HTTPS connection to the device web server. Use one of the following values.
none: The server certificate is not validated.relaxed: The server certificate is validated if one is presented by the server. This is the default.strict: The server certificate is validated and it is an error if the server does not present a certificate.
Enable (true) or disable (false) extended (domain name) certificate validation.
If set to true, WebTunnelAgent will verify that the common name (or one of the
Subject Alternative names) of the server certificate matches the device IP
address. Should be set to false, as most devices don't have TLS certificates
matching the device domain name or IP address.
This setting specifies a directory or file containing trusted root certificates for OpenSSL. Can be left empty to use the built-in default OpenSSL root certificates. Please note that OpenSSL on Windows may not include a list of trusted root certificates.
This optional setting specifies the path to an X509 certificate file in PEM format used for authenticating the agent against the device web server (together with a private key, specified using tls.privateKey property) if HTTPS is used.
This optional setting specifies the path to an X509 private key file in PEM format used for authenticating the agent against the device web (together with a certificate, specified using tls.certificate property) if HTTPS is used.
WebTunnelAgent supports a very flexible logging configuration, allowing fine-grained
control over the amount of logging data produced. Logging information can be written to the
console, to a log file, or to the syslog daemon.
Logging is based on the concept of loggers, channels and formatters. A logger creates a log message, which is then formatted using a formatter, and then sent to a channel. The kind of channel decides whether the message is written to the console, to a file, or to the syslog daemon. Loggers form a hierarchy, with a special logger, the root logger, at the base. A logger inherits its configuration from the logger(s) above in the hierarchy. If only the root logger is configured, all loggers will inherit the configuration of the root logger. In the following, we will only configure the root logger, as this is sufficient for most production purposes. A logger’s configuration consists of the channel the logger is connected to, as well as its log level. Every log message is tagged with a priority, or log level. A logger will only forward messages with a priority higher than the configured log level. The following priorities or log levels are available:
none(turns off logging)fatal(highest priority)criticalerrorwarningnoticeinformationdebugtrace(lowest priority)
This setting specifies which channel is connected to the root logger. A channel with the
name specified here must be defined in the configuration file, otherwise the application
won’t start up. The default configuration file specifies two channels, one
named console and one named file. Additional channels can be added if necessary.
This setting specifies the log level of the root logger. Specify one of the log levels
none, fatal, critical, error, warning, notice, information, debug or trace.
The lower the level, the more information will be logged. For production purposes,
the log level notice or warning is recommended.
This setting creates a channel named file for writing to a log file (FileChannel).
This setting specifies the format of the log messages for the file channel. See Logging Format Placeholders for a list of supported format placeholders.
The path of the log file.
The log file rotation strategy. Log files can be rotated based on size or time interval. Rotating a log file means closing the current log file, renaming ("archiving") it, and creating a new log file. The following values can be given:
never: No log rotation. The log file will grow indefinitely. Default.[day,][hh]:mm: The log file is rotated on specified day/time.dayis specified as long or short day name (Monday/Mon, Tuesday/Tue, ... ) and can be omitted, in which case log is rotated daily.hh: hour – valid hour range is 00-23; can be omitted, in which case log is rotated every hour.mm: minute – valid minute range is 00-59 and must be given.
daily: the file is rotated daily.weekly: The file is rotated every seven days.monthly: The file is rotated every 30 days.<n> minutes: The file is rotated every<n>minutes, where<n>is an integer greater than zero.<n> hours: The file is rotated every<n>hours, where<n>is an integer greater than zero.<n> days: The file is rotated every<n>days, where<n>is an integer greater than zero.<n> weeks: The file is rotated every<n>weeks, where<n>is an integer greater than zero.<n> months: The file is rotated every<n>months, where<n>is an integer greater than zero and a month has 30 days.<n>: The file is rotated when its size exceeds<n>bytes.<n> K: The file is rotated when its size exceeds<n>Kilobytes.<n> M: The file is rotated when its size exceeds<n>Megabytes.
NOTE: For periodic log file rotation (daily, weekly, monthly, etc.), the date and time of log file creation or last rotation is written into the first line of the log file. This is because there is no reliable way to find out the real creation date of a file on many platforms (e.g., most Unix platforms do not provide the creation date, and Windows has its own issues with its "File System Tunneling Capabilities").
Using this setting it is possible to specify whether the times used for rotation are in UTC or local time. The following values are supported:
utc: Rotation is based on UTC time (default).local: Rotation is based on local time.
Using the this setting it is possible to specify how archived log files are named. The following values are supported:
number: A number, starting with 0, is appended to the name of archived log files. The newest archived log file always has the number 0. For example, if the log file is namedWebTunnelAgent.log, and it fulfils the criteria for rotation, the file is renamed toWebTunnelAgent.log.0. If a file namedWebTunnelAgent.log.0already exists, it is renamed toWebTunnelAGent.log.1, and so on.timestamp: A timestamp is appended to the log file name. For example, if the log file is namedWebTunnelAgent.log, and it fulfils the criteria for rotation, the file is renamed toWebTunnelAgent.log.20190510113000.
Archived log files can be automatically purged, either if they reach a certain age, or if the number of archived log files reaches a given maximum number. This is controlled by the purgeAge and purgeCount settings.
The purgeAge property can have the following values:
<n> [seconds]: The maximum age is<n>seconds.<n> minutes: The maximum age is<n>minutes.<n> hours: The maximum age is<n>hours.<n> days: The maximum age is<n>days.<n> weeks: The maximum age is<n>weeks.<n> months: The maximum age is<n>months, where a month has 30 days.
This setting specifies the maximum number of archived log files. If the number is exceeded, archived log files deleted, starting with the oldest.
Archived log files can be compressed using the gzip compression method. The following values are supported:
true: Compress archived log files.false: Do not compress archived log files.
This setting creates a channel named console for writing to standard output (ColorConsoleChannel).
This setting specifies the format of the log messages for the console channel.
See Logging Format Placeholders for a list of supported format placeholders.
%s: message source%t: message text%l: message priority level (1 .. 7)%p: message priority (Fatal, Critical, Error, Warning, Notice, Information, Debug, Trace)%q: abbreviated message priority (F, C, E, W, N, I, D, T)%P: message process identifier%T: message thread name%I: message thread identifier (numeric)%N: node or host name%U: message source file path (empty string if not set)%u: message source line number (0 if not set)%w: message date/time abbreviated weekday (Mon, Tue, ...)%W: message date/time full weekday (Monday, Tuesday, ...)%b: message date/time abbreviated month (Jan, Feb, ...)%B: message date/time full month (January, February, ...)%d: message date/time zero-padded day of month (01 .. 31)%e: message date/time day of month (1 .. 31)%f: message date/time space-padded day of month ( 1 .. 31)%m: message date/time zero-padded month (01 .. 12)%n: message date/time month (1 .. 12)%o: message date/time space-padded month ( 1 .. 12)%y: message date/time year without century (70)%Y: message date/time year with century (1970)%H: message date/time hour (00 .. 23)%h: message date/time hour (00 .. 12)%a: message date/time am/pm%A: message date/time AM/PM%M: message date/time minute (00 .. 59)%S: message date/time second (00 .. 59)%i: message date/time millisecond (000 .. 999)%c: message date/time centisecond (0 .. 9)%F: message date/time fractional seconds/microseconds (000000: 999999)%z: time zone differential in ISO 8601 format (Z or +NN.NN)%Z: time zone differential in RFC format (GMT or +NNNN)%E: epoch time (UTC, seconds since midnight, January 1, 1970)%L: use local time zone for dates and times (must be specified before any of the date/time placeholders)%%: percent sign