AnyX Guide Topic: connector

  • Agilicus Connector – QNAP

    Agilicus Connector – QNAP

    qnap ts-133

    Agilicus Connector – QNAP

    Install the Agilicus connector on a QNAP NAS

    QNAP Background

    A QNAP NAS runs a custom Linux operating system, providing storage and other services in a consumer and small to medium business environment.

    Installing the Agilicus Connector on the NAS can facilitate accessing the shares remotely, as well as providing a means of remote management.

    Install

    The Agilicus Connector will run as a container on the QNAP. In order to do this, you must have the Container Station feature enabled.

    Enable QNAP Container Station

    Create Agilicus Connector as Container

    There are two methods to this: via the QNAP Web management interface, and, via the QNAP shell. Both achieve the same objective. If you use the QNAP Web management interface, be aware there is an expiry time on the challenge-id when you are copying from the Agilicus admin interface.

    Option 1: QNAP Web interface

    You will copy 3 fields from the Agilicus connector install screen (Resources/Connectors/New): two environment variables, and one image. The image should be cr.agilicus.com/pub/images/agilicus-agent/client:stable and the environment variables will be AGILICUS_CHALLENGE_ID=XXX and AGILICUS_CHALLENGE_CODE=XXX. These latter two are only good for a few minutes, regenerate if it takes you longer.

    You will likely want to mount /Share into /Share (via bind host mount path), allowing re-exporting shares via Agilicus Share.

    Option 2: Paste via Shell

    The command line given from the Agilicus Admin interface on the install new connector, docker tab, will work as-is, you can just paste it. However, you will likelywant to mount /Share into /Share (via bind host mount path), allowing re-exporting shares via Agilicus Share. You can achieve this by adding -v /Share:/Share into the command line before the image. This will look like:

    docker run -d --name agilicus-connector --net=host -v agilicus_cfg:/etc/agilicus/agent -e AGILICUS_CHALLENGE_ID=XXXXXXXX -e AGILICUS_CHALLENGE_CODE=XXXX -v /Share:/Share cr.agilicus.com/pub/images/agilicus-agent/client:stable

    You can check the status or logs with

    docker logs -f agilicus-connector

    QNAP Enable Shell Access

    Below are two methods to enable a shell on the QNAP. Both will achieve the same objective.

    Option 1: Enable SSH

    Using the instructions at https://www.qnap.com/en/how-to/faq/article/how-do-i-access-my-qnap-nas-using-ssh, namely: “Control Panel/Network & File services / Telnet/SSH, Allow SSH connection”.

    Option 2: Web Shell

    Using the instructions at https://www.myqnap.org/install-the-repo/,

    From the MyQNAP menu on the left, select ‘search’, enter ‘gotty’, and install.

    You may now open a shell as:

    Once in the shell, login as your username/password

  • Site To Site Transparent Layer 3 Tunnel

    Site To Site Transparent Layer 3 Tunnel

    Overview

    In this sample, we are going to use a single service forwarder to transfer a port from the local connector to a remote connector, and, over top of that, run a web socket UDP tunnel, and, over top of that, run a Wireguard VPN. This will provide layer 3 adjacency. We will use wstunnel to facilitate. We will use the Agilicus connector to facilitate the inbound/outbound connectivity, and, authenticate via a Service Account for always-on operation.

    For the sample, we assume the main site and the remote site(s) each have a device running Linux (the sample is for Debian or Ubuntu). We also assume the sites have non-overlapping IP (avoiding the need for NAT in either of the directions).

    High Level Steps

    1. Create a connector on each of ‘Main site’ and ‘Remote site’
    2. Create a network on Remote Site, using destination 127.0.0.1, port 4443
    3. Create a service forwarder, via ‘Main Site’, listening on 127.0.0.1 port 4443, destination the network created above
    4. Run ‘wstunnel’ on Remote site, listening for connections on 127.0.01 4443
    5. Run ‘wstunnel’ on Main site, sending connections to 127.0.0.1, port 4443
    6. Run wireguard on each of the sites, using wstunnel as the source/sink

    Agilicus Connector & Network Setup

    In this example, we assume your domain is connect.example.org. This you would use https://admin.connect.example.org for administration. We assume you are going to have two sites connected, ‘main’, and ‘remote-1’ (you can later add more remotes).

    Main: Connector & Service Account & Application Setup & SSH

    On the ‘main’ site, install an Agilicus Connector.

    Now we will create a ‘application’ to use this Connector. First, we will create a Service Account, a special system user that will have always-on permission to use it.

    Now, we will create an “application’ to use this Connector.

    Now we will assign permissions to the Service Account we created above:

    Download and save the ‘Authentication Document’ for this Service Account, we will use it below. Also, copy and save the service account email, we will use that below.

    Now, let us setup SSH so we can remotely administer this device:

    NOTE: feel free to modify the options. The ‘DISCUSS’ on users auto-signing in, this may be a convenient way to use a browser-based sign in without giving users the password of the device.

    At this stage we are complete setting up ‘main’.

    Remote: Connector & SSH

    Install the connector as above in main, switching the connector name to remote-1.

    Setup SSH as above in ‘main’, switching the connector to remote-1 and the SSH name.

    Checks

    If we examine the connector screen, we can see that each of our new connectors exists, and has SSH bound to it, as well as ‘main’ has the wireguard service from the application we created:

    We can also check by opening https://profile.connect.example.org and hitting refresh, we should see an SSH icon for each, and, if selected, should be able to sign-in. NOTE: we recommend creating an SSH key and using the native integration for a more seamless and secure experience.

    Linux Setup

    We now have some Linux-specific setup to do, outside the scope of Agilicus AnyX. This is to install a site-to-site connectivity agent called ‘wireguard’ and a WebSocket tunnel to facilitate it.

    Install Wireguard: Main

    On the ‘main’ site Linux device, run the following commands as root (e.g. run sudo su - first):

    Install Wireguard: Remote

    On the ‘remote’ site Linux device, run the following commands as root (e.g. run sudo su - first):

    Add Remote Trust to Main

    On the ‘main’ site Linux device, run the following commands as root (e.g. run sudo su - first). This will cause it to trust the remote.

    Examine Wireguard Configuration

    Now, let us examine the configuration. On the ‘main’ site, run cat /etc/wireguard/wg0.conf’ and observe the output, as below:

    Reading, we can see that the ‘server’ has a private key, and the remotes it trusts have a public key. Also, the ‘main’ is going to have an IP of 10.8.0.1, we will assign 10.8.0.2 to the remote.

    On the ‘remote’ site, let us also examine the config. We can see the assign of the 10.8.0.2 IP

    WebSocket Tunnel Setup

    On both of the sites, run the following to install the WebSocket tunnel facility:

    Main WebSocket Setup

    Now, on the ‘main’ site, we will setup WebSocket to listen:

    We can now check that it is running:

    Remote WebSocket Setup

    Now on the ‘remote’ site, we will setup the WebSocket tunnel. First, we will create an API Key which gives us permission to the Service Account we created above. There is no exposed facility in the Web administration to create API keys, so we will use the CLI. You can do this on your Windows machine, or, on the Linux machine. The machine needs Python installed, see https://www.python.org/downloads/windows/ .

    First we will install the Agilicus CLI & SDK using ‘pip install -U agilicus’ (this works equally on Windows or Linux).

    Then, we will list the users of type service_account to find the one we created above. A browser will open the first time to obtain your credentials for this operation.

    Now, we will create an API key using the Service Account credentials we downloaded above:

    It will output something like below. the api_key: XXX is the important part.

    The Network can be accessed using the service account ’email’ we obtained above, and the API key we just created.

    Let us test the API key with curl. First, lets see that if we open it with a browser, we are forced to try and sign in (we will not be able to sign-in, but this will tell us the application is up). Now, let us try with curl. Fill in your values on the first two lines, and, replace connect.example.org with your domain.

    We should see a response like:

    OK, now that we have tested the connection, let us install the remote-1 site tunnel. Fill in your values on the first two lines, and, replace connect.example.org with your domain.

    OK at this stage we are done and the connection should be up, and will stay up, restarting as needed if the network goes down.

    Checks

    Let us bring up the Wireguard interfaces, and diagnose. On each machine, run wg-quick up wg0

    Now, we should see the interfaces up. On each run wg and check:

    From the remote, we should be able to ping 10.8.0.1, and from main we should be able to ping 10.8.0.2:

    We can check logs:

    We can check the interfaces:

    Routing

    Now that we have the point to point interfaces up, we may wish to reach local peers on one side or the other. First, let us check routing is enabled:

    Now, devices on the remote side will need a route installed, using the lan-side IP of the Linux device. Similarly, the main side devices will need a route installed, using the lan-side IP of the Linux device.

  • WAGO Edge Controller

    WAGO Edge Controller

    wago

    WAGO Edge Controller

    The WAGO Edge Controller is a flexible and open control platform for many embedded and industrial applications. It provides an excellent vantage point to run the Agilicus Connector.

    WAGO Edge Controller

    The WAGO Edge Controller is a flexible and open control platform for many embedded and industrial applications. It provides an excellent vantage point to run the Agilicus Connector.

    The below instructions were tested on firmware 04.04.03(26) on the following devices:

    WAGO Compact Controller CC100 751-9301

    WAGO Controller PFC200 750-8212

    There are two deployment methods available on the platform:

    1. Native Install. The Agilicus Connector runs as part of the baremetal Host Linux distribution
    2. Docker Install. The WAGO Edge Controller runs a container runtime

    Since the Agilicus Connector has no local state other than the encryption keys, there is no specific preference as to which method to choose. If you are using Service Forwarders inbound to the device, you will likely want the native install to enable Machine to Machine communication from a local network.

    Preparation

    NOTE

    Agilicus AnyX uses modern cryptography which requires proper time. Please ensure NTP is configured.

    Requirements

    In order to deploy the Agilicus Connector successfully the following steps should be undertaken

    • Verify that sufficient (~200MB) disk space or expanded storage is available (Typical 1.1GB onboard eMMC available)
    • Enable SSH terminal access via Web UI
    • Configure and Sync NTP based time
    • Have WAN access with DNS resolution and network segmentation permitting the Controller to reach the Agilicus AnyX cloud IP address over TLS

    Confirm SSH is Enabled:

    454eb14e 2024 07 24 15 33

    Confirm that your Controller has access to a local or remote NTP Server in order to maintain accurate time

    31d25b4e 2024 07 24 15 35

    Option 1. Native Install

    The WAGO Edge Controller natively supports the Agilicus Connector. Install the connector as usual, selecting ‘Linux’, and paste the given command into an administrative (root) shell via SSH.

    9266b326 2024 07 25 10 13

    The results will look as below:

    You can verify the Agilicus Connector instance status in the Connector Overview interface.

    76f67855 2024 07 24 16 04

    Option 2. Docker Install

    NOTE

    Currently the docker installation support is restricted to 64bit ARMv8 architecture. Support for the 32bit ARMv7 is pending, we recommend Option 1 for these models. Contact us if you are unsure which architecture your controller uses.

    Additional Requirements

    As a primer, make sure to consult the WAGO documentation for the latest supported hardware and configurations of Docker.

    If using Docker, make sure you understand the requirements of installing and running Docker service on the controllers with the WAGO Quickstart Guide on Docker available here:

    https://www.wago.community/t/how-to-getting-started-with-docker/95

    • Verify that the WAGO Controller model supports Docker
    • Deploy and Enable Docker via Web UI

    Confirm Docker is enabled on the device by logging into the Web Interface:

    bfd172a6 2024 07 24 15 31

    SSH to the Controller with the admin credentials and elevate your session to root privileges:

    44e78d84 2024 07 24 15 37

    Verify that docker is installed:

    5153d937 2024 07 24 15 38

    Create and Deploy AnyX Connector

    Navigate to your Agilicus AnyX Admin page for your organisation and create a new connector instance under Resources -> Connectors -> New

    Once created, proceed with Installation and select the Docker tab in the installation menu:

    17465d96 2024 07 24 15 44

    Copy the text block by clicking on the blue “Copy” icon.

    Paste the text block in your Controller SSH Session:

    5655d58f 2024 07 24 15 47

    Verify that docker is now running an ‘agilicus-connector’ container

    3d7dc23c 2024 07 24 15 54

    Verify in the Agilicus AnyX admin interface that the connector instance is up and communicating with the cloud platform. The Instance dialog should display the WAGO controller hostname and a status of GOOD:

    76f67855 2024 07 24 16 04

    Troubleshooting

    If the docker installation fails or the container fails to start, running docker logs will provide a lengthy and verbose output of the installation and initialisation process of the container.

    c20befec 2024 07 24 16 07

  • Agilicus Connector – NanoPI R2S

    Agilicus Connector – NanoPI R2S

    NanoPI R2S

    NanoPI R2S

    Simple Embedded System with Agilicus Connector

    NanoPi R2S Background

    The NanoPI R5S has 2 x Gigabit Ethernet, 1GiB of RAM, and 32GB of eMMC storage. With its large passive heatsink it is an ideal platform to use as a small router. It also makes an ideal platform to run the Agilicus Connector.

    The NanoPi R2S will run several operating systems (Ubuntu, Armbian, OpenWRT). In this document we discuss using it with OpenWRT.

    Installing OpenWRT

    As received, the NanoPi R2S will (usually) be running FriendlyWRT. You may feel free to use this, however it has some security flaws. Agilicus recommends using the native OpenWRT build. You may build it yourself, or obtain from the OpenWRT Project.

    267cb5d7 image
    1. Connect your laptop to the LAN ports (furthest to the USB-C power connector).
    2. Open a browser to http://192.168.2.1/
    3. Sign in as ‘root’, password ‘password’
    4. Navigate to ‘System/eMMC Tools’
    5. Download (on your laptop) https://downloads.openwrt.org/releases/23.05.3/targets/rockchip/armv8/openwrt-23.05.3-rockchip-armv8-friendlyarm_nanopi-r2s-squashfs-sysupgrade.img.gz
    6. Select ”Choose File’ and the file you just downloaded
    7. Select ‘Upload and Write’
    8. Wait approximately 90 to 120 seconds

    At this stage you are running the Agilicus-supplied OpenWRT image.

    2e822959 image
    7999e14d image
    d95df461 image
    4905dfb9 image

    Agilicus Connector Install

    Using the Agilicus administrative portal, create a new connector. Use the ‘Linux’ instructions, copy.

    In the OpenWRT admin interface (http://192.168.2.1/), select ‘Services/Terminal’. Sign in as root and the password you selected. Paste (shift-insert).

    At this time the connector should be installed and you may close the terminal.

    24b5a7dc image
    8bfda54e image

    You may wish to enable access to this router via the Agilicus AnyX platform (notably SSH and Admin web interface).

    NOTE: DHCP Server Enable

    Depending on your use, you may wish to have a DHCP server on the LAN ports, you can enable this under ‘Network/Interfaces/LAN’. You may also configure your desired IP range here.

    It is appropriate to have a DHCP server on these LAN ports if this is an isolated network. If you are connecting to a larger network with an existing DHCP server, you probably wish to instead change the protocol on the LAN ports to DHCP Client.

    3a0fb06e image
    1e4619ff image

    NOTE: Time Sync (NTP)

    Modern cryptography requires clock sync and accuracy on all devices. Typically this is performed via Network Time Protocol, however, in some environments this is blocked (e.g. HTTPS-only outbound).

    If your clock is not sync’d (see System/Time Synchronisation menu), you might be able to use a local NTP server. If not, you can enable an HTTPS-based sync as below:

    This is going to use the Agilicus API to provide an HTTP-based (over HTTPS port 443) time service. Configuration can be observed in /etc/config/htpdate:

    Security Hardening

    Web Terminal Disable

    f00fff0e image

    Once you have installed the Agilicus Connector, we recommend disabling the web terminal. On ‘Services/Termina’, select the config tab and remove the check-box beside ‘Enable’.

    You may re-enable the web terminal later if you need it. However, we recommend using SSH instead for future command-line access.

    The web terminal operates on a secondary TCP port (7681) and is not needed for normal operation.

    SSH Setup

    94a026d2 image

    Agilicus recommends disabling password access to SSH in favour of SSH Keys.

    On System/Administration, the SSH Access tab, uncheck ‘Password authentication’ and uncheck ‘Allow root logins with password’.

    The rationale here is that password stuffing and guessing is a thing. Eventually someone will guess your l33t-hax0r password. Removing any ability to use passwords reduces the risk. In some controls environments any passwords can be disallowed.

    dc2dee2c image

    Once you have disabled password access, we recommend adding a SSH Key. Agilicus recommends using ed25519 SSH keys since they are smaller and more secure. Add your public key to the router here and place the private key (with passphrase!) in your SSH Agent on your desktop.

    SSH keys are not only more secure, but also more convenient.

    One downside to note: the Agilicus web interface for SSH is not currently compatible with SSH keys. If you wish to have SSH access to this device via the Agilicus Profile web interface, keep password on.

    Firewall

    At this stage, configure the firewall and NAT settings to suit on each of the interfaces. If the Agilicus Connector is providing Service Forwarder services, remember to open this ports on the router too.

    We can check which ports are listening by running netstat -nlpt as below. Things with 0.0.0.0:PORT are available from outside the device. Things listening on 127.0.0.1, fe80::, ::1, etc, are locally bound only. In the example below, ‘uhttpd’ (the admin web interface), ‘dropbear’ (SSH) and ‘ttyd’ (the web terminal) are the only things listening.


    Sample Configuration: Connect to Local HTTP + SSH

    This walk through shows an example of how, once the connector is installed (as per above), configuration of an HTTP and SSH interface to this local device. Once these are configured you could use the firewall to disable all external access. The high level steps are:

    1. Create Connector (Agilicus Admin)
    2. Install Connector (NanoPi Web Terminal)
    3. Create SSH Resource (Agilicus Admin)
    4. Create Web Resource (Agilicus Admin)
    5. Assign Web Resource Permission (Agilicus Admin)
    6. SSH to NanoPi from Agilicus Profile (Agilicus Profile)
    7. Open Web Interface to NanoPi (Agilicus Profile or direct)

    OK, let’s get started. This will take approximately 5 minutes.

  • Phoenix Contact PLCnext AXC F 2152

    Phoenix Contact PLCnext AXC F 2152

    3875d2dc phoenix contact plcnext axc f 2152

    Phoenix Contact PLCnext AXC F 2152

    Install the Agilicus connector directly on the PLC for highest security and simplest deployment.

    Phoenix Contact PLCnext AXC F x152

    The Phoenix Contact PLCnext AXC F 2152 (and 1152 and 3152) provide an ideal platform to run the Agilicus Connector. It has enough storage, CPU, its in the right vantage point in the network. Once installed, you can use it for programming, or for operations.

    The installation is the same as all other Linux platforms.

    First, we SSH into the PLC. This is typically ssh admin@plc with username ‘admin’ and password ‘plcnext’.

    Next we must enable the root password if we have not already:

    At this stage we can become root:

    At this stage, go to the Agilicus admin interface and create a new connector. Select the ‘Linux’ install and paste into the ssh window above:

    As a reminder, this command line times out in 10 minutes, if you have note done those steps above first, just regenerate the command-line

    The correct output will look something like below. You may need to have DNS enabled and NTP (for time).

    NOTE: Enable NTP via you may wish to set the timezone to UTC first:

    ln -sf /usr/share/zoneinfo/UTC /etc/localtime

    At this stage we can check its running. In the Agilicus admin interface, the connector line will go ‘GREEN’ (Good) within a minute or so. We can also test on the PLC:

    that line should show the service running.

    The Agilicus Connector also works on the PLCnext simulator.

  • Agilicus Connector – Container/Docker

    Agilicus Connector – Container/Docker

    container

    Agilicus Connector – Container

    Agilicus Connector – Container/Docker

    Many desktop, server, embedded systems support container runtimes. The most widely used syntax and name recognition, Docker, gives a convenient simple command-line interface.

    The Agilicus connector can natively run inside a connector. This provides a convenient method of experimenting (or deploying) with low cost, high simplicity.

    For people wishing to run the connector on an Apple MAC, this is the best approach.

    89bd4540 image

    Create the connector as normal, select ‘Docker’ from the install type tab at the top and paste into the machine running the container runtime.

    By default this command creates a volume ‘agilicus_cfg’ and uses ‘host’ networking.

    Two ephemeral security identifiers (CHALLENGE_ID, CHALLENGE_CODE) are provided, these are claimed once and then discarded. You must paste the command line within 10-minutes of generating it.

    Once complete, you will see the connector come online as normal.

    Note: for a ‘share’, you may need to mount a volume into the container (e.g. -v /Documents:/Documents), otherwise only the internal filesystem of the container is available.

  • Agilicus Connector Sign-In

    Agilicus Connector Sign-In

    44af8972 connector

    Connector Install: Sign-In

    Installing an Agilicus Connector creates a new type of user, a service account.

    Connector Install: Sign-In

    5f9c4c7a image

    Installing an Agilicus Connector creates a new type of user, a service account. This service account is created automatically for you, using your (the administrators) privilege as a bootstrap. This service account has a restricted set of abilities. You may see (and delete after deleting a connector) in the admin front end under ‘Access/Service Accounts’.

    Once this service account is created, the Connector will use this identity without further user intervention.

    In order to create the service account, and get its credentials, the install process needs you to authorise it. To do this, 2 methods exist (both yield identical results):

    1. Open a new browser, request you to sign in. This in turn uses a ‘callback’ URI that points to the host you are trying to install the connector on. Your browser, upon finishing the sign-in flow, will do a redirect to http://localhost:<someport>, passing the access token forward.
    2. Copy a URL you are given, paste it into your browser, this will give you a code, paste that back into the location you started the install from.
    9b6015ba image

    Typically if you are using a graphical desktop operating system, and signed into it as yourself, you would use method #1. If you are remotely accessing a system, or it is a headless embedded device, you would use method #2.

    dce3169f image

    In some cases both methods are available, in which case the first one to answer will be used.

    Note: The Connector installation process should be run with Administrative (e.g. Root, LocalAdmin privilege). If you do not, it will attempt to elevate for you (as you can see in the below example).

    8467c1f9 image

    A console log of the initial install process is shown below. In this example, you would have seen your browser open automatically with a sign-in screen as above right. If you sign in this way, the installation will complete.
    Instead, you may copy the URL given (https://auth.YOURDOMAIN/auth?client_id=agilicus-builtin-agent-connector…) into the browser on your desktop. You will then see a screen as shown. Copy the token (osfygqo2j…) and paste it in where it says “Enter verification code:“, and the installation will complete.

    Whichever method you use, you will achieve the same result, and the Agilicus Connector will need no further intervention.



  • Agilicus Connector – Microsoft Windows

    Agilicus Connector – Microsoft Windows

    Windows Install

    Microsoft Windows

    Install the Agilicus Connector on Microsoft Windows.

    Versions Supported

    The Agilicus Connector will run on any version of Windows XP or later. However, prior to Windows 10, the ‘curl’ command, used as part of the install, was not present, and you may need to manually install it.

    If your Windows version is old or unpatched, it may be missing the Let’s Encrypt Intermediate certificate, see https://letsencrypt.org/certificates/

    Installation

    71ec8c56 image

    Windows 10 and later come with a command pre-installed called ‘curl‘ that allows for 1-click automatic install.

    To create and install a connector, first, on your desktop PC (where you have the ADMIN url open), go to ‘resources/connectors/new’. Give your connector a name that means something to you (often the name of the machine you will install it on, or the site that it connects).

    Click ‘create’. You will now be given the option to ‘Install Connector’. This brings up a dialog box as below. Select ‘WIndows – CMD’.

    0f9dac90 image

    There is only 1 question on this dialog “This is a subsequent connector (create a cluster)”. Select this if you have more than one computer running the same connector instance in a high-availability cluster.

    Select the ‘COPY’ button. This will place the command line into your clipboard.

    At this stage we must switch to the computer where you will run the connector. It might be this same machine, it might be another accessible via Remote Desktop or VNC.

    4133a790 image

    On the target computer, open a ‘Command Prompt’ as administrator:

    1. Go to ‘Start’
    2. Type ‘cmd’
    3. Right click ‘Command Prompt’
    4. Select ‘Run as administrator’

    This will open a ‘cmd’ shell.

    We can quickly test that ‘curl’ is installed by running ‘curl ifconfig.me’. This will print our current public IP address. Curl is pre-installed as part of Windows as for Windows 10 and Windows 2016. If you do not have curl installed, you may try the PowerShell instructions from the dialog, or, install curl manually.

    67370dff image

    We can now paste the command we obtained from the ADMIN UI.

    Paste the command as below. The correct output will be similar to what is shown, ending in ‘Installation Complete’

    It is possible you will run into some errors, the most common relate to:

    1. Time setup. Your computer should be time-synced (using NTP). This is important for proper cryptography.
    2. Firewall. Your computer may block outbound access to https://www.agilicus.com
    3. Intermediate Certificate. If your computer has not run Windows update since 2021, it may be missing the Let’s Encrypt intermediate certificate.
    6d5adf6c image

    At this stage you are complete and may close the command window.

    In the ADMIN UI you can check the status of your connector, it should move to ‘GREEN/GOOD’ (you may need to refresh this screen).

    General Notes

    NOTE: Timeout

    For security reasons, the command you will paste has a time limit before it expires of 10 minutes. If it expires, simply generate a new one in the ADMIN interface and paste it.
    In this case, you will see an error like: “Installation failed due to the following error: could not claim challenge code: 400 Bad Request. Do not run the command again; generate a new one. See https://www.agilicus.com/anyx-guide/agilicus-connector/#h-installation

    NOTE: WebClient Service

    You may need to manually enable the Windows WebClient service if you will use the connector to mount a remote WebDav Share to this machine. Normally this is set to run on demand, but in some environments it may be disabled.

    NOTE: Windows Failover Clustering High Availability

    To configure the Agilicus Agent for 1+1 ACTIVE/PASSIVE on Windows Cluster Server, use a Generic Service. For more information, see Agilicus Windows Cluster Server

    NOTE: Windows Defender False Positive

    Some installations have observed, using the PowerShell installation instructions, a false-positive detection for Trojan:Script/Sabsik.TE.B!ml. This has been submitted to Microsoft for re-evaluation, but they have been unable to reproduce. If this occurs, you can override this detection for this specific binary.

    NOTE: 2012 PowerShell: Could not create SSL/TLS secure channel

    Older versions of Windows may be missing the R3 root certificates (see Microsoft note). This can prevent usage of modern cryptographic https sites. Let’s Encrypt has more information, including a diagram of the full chain of trust.

    You may find you need to run Windows Update, or, manually remove the old R3 intermediate and add the new one from Let’s Encrypt.

    NOTE: CHANGE RUNNING USER/PERMISSIONS

    In some circumstances you may change the user the connectr runs as (the windows service user) after initial installation. If you do this, it is important to change ownership of all of the files in C:\Program Files\Agilicus to make the user.

    Diagnostic Logs – Windows Eventvwr

    The Agilicus Connector sends diagnostic and access logs to Windows Eventvwr by default. To view these logs on a standalone-basis, you might consider creating a custom view.

    1. Open Microsoft Windows eventwr (from Start menu, type ‘eventvwr’)
    2. Right click in custom views
    3. Create Custom View
    4. Select ‘By Source’, and ‘agilicus-connector‘. Enable each Event Level of interest (e.g. Critical, Warning)
    5. Save as ‘Agilicus Connector Logs’
    af64c331 image
    b1e55a82 image
    d40dd28d image

    Once this is complete, you will see a new custom view as below. You may then browse the logs or e.g. right-click and save a text file for forwarding.

    0acbf337 image

    File Permissions Correction

    If your connector shows a warn status, it could mean that the file does not have sufficient permission for Agilicus’ connector. To give access files/folders the correct permissions, 

    Automatic Permission Fix Instructions

    Download and run this script (in Powershell) as access.ps1, or, follow the manual instructions below.

    $path="C:\Program Files\agilicus"
    $user=Get-CimInstance -Class Win32_service -filter "Name = 'agilicus-agent'"| select -expand startname
    if ( $user -Match "LocalSystem" ) { $user="NT AUTHORITY\SYSTEM"}
    $acl = Get-ACL -Path $path
    $AccessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($user,"FullControl","ContainerInherit,ObjectInherit","None","Allow")
    $acl.SetAccessRule($AccessRule)
    $acl.SetAccessRuleProtection($False,$True)
    $acl | Set-Acl -Path $path
    

    Manual Permission Fix Instructions

    See which user accounts are running the service

    1. Right-click on the Start button to open the WinX Menu
    2. Select Run
    3. Type services.msc in the Run box which opens
    4. Windows Services Manager will open.
    5. Under the Name column, you will see Agilicus Connector
    6. You will see the user running this service in the Log On As Column

    Update the Folder with correct user/permissions

    1. Right-click the folders (Typically “C:\Program Files\agilicus”)
    2. Select Properties. The Properties dialog box appears.
    3. Access the Properties dialog box.
    4. Select the Security tab.
    5. Click Edit. The security tab opens in a new window.
    6. Click Add… The Select Users, Computers, or Groups dialog box appears.
    7. In the Enter the object names to select text box, type <username> and check
    8. Click OK. The Properties dialog box reappears.
    9. Click OK on the Security window.
    10. Access the Properties dialog box.
    11. Select the Security tab.
    12. Click Edit
    13. In the Group or user name section, select <username> 
    14. In the Permissions section, use the checkboxes to select Full control Allow
    15. Click Apply
    16. Click Okay
  • OpenWRT Connector Install

    OpenWRT Connector Install

    OpenWRT Login LUCI

    OpenWRT Connector

    Overview

    The Agilicus Connector can install on an embedded router product such as OpenWRT. The devices (usually) have either an MIPS or an Arm processor. The instructions are the same for each, but the link is different. The instructions below are for a OpenWRT Router but will be similar on other devices. Select the proper processor (ARM/MIPSBE/MIPSLE) according to your hardware.

    See NanoPi R5S for a specific device and instructions.

    RESOURCE REQUIREMENTS

    Your OpenWRT device will need at least 128MiB of flash memory, and at least 256MiB of DRAM. Not all devices do, we recommend checking first.

    No changes are needed to your firewall. No VPN is needed. You can administer users via their Active Directory or Apple, Google, Linkedin accounts.

    The high level steps are:

    1. Enable SSH on your Router (or, use the web-based terminal from LUCI)
    2. Create a Connector (Agilicus admin interface)
    3. SSH to the Router
    4. Paste the given command line

    after this, the Agilicus Connector will be entirely automatic, and controlled via the Agilicus admin interface. You may uninstall it at any time with

    Create Connector

    First we will create a Connector. This logical endpoint allows reverse inbound connectors to safely occur.

    1a53ec15 image

    We give the connector a name. This is used for statistics and diagnostics purposes. Select the Linux instructions, and select Copy.

    9cb9a7ff image

    Now, SSH to your Router and paste the given command line:

    At this stage you are complete, you will see the Connector go online in the web interface in a minute or so.

  • Agilicus Connector Mikrotik Router

    Agilicus Connector Mikrotik Router

    Agilicus Connector Mikrotik Router RB5009UG+S+IN

    MikroTik RouterOS

    Install as a container, direct on the router.

    Overview: Agilicus Connector Mikrotik Router

    The MikroTik RB5009UG+S+IN is a small-form factor router. it is a good vantage point to run the Agilicus Connector. NOTE: this is an ARM-based device, not X86.

    Other MikroTik devices may work as well, MikroTik has a broad family of devices. In order to be appropriate for the Agilicus Connector, they need to support:

    1. container package
    2. ARM or x86 processor
    3. 100MiB or more of storage space
    4. 256MiB or more of memory

    The below instructions were tested on the RB5009UG+S+IN with v7.8 and v7.9RC, specifically:

    /system/resource/print
                       uptime: 16h23m57s
                      version: 7.8 (stable)
                   build-time: Feb/24/2023 09:03:00
             factory-software: 7.1
                  free-memory: 3830.4MiB
                 total-memory: 3904.0MiB
                          cpu: AMD
                    cpu-count: 2
                cpu-frequency: 2903MHz
                     cpu-load: 0%
               free-hdd-space: 915.7MiB
              total-hdd-space: 980.0MiB
      write-sect-since-reboot: 301984
             write-sect-total: 301984
            architecture-name: x86_64
                   board-name: CHR
                     platform: MikroTik

    The below instructions were performed using the MikroTik CLI. They may also be performed via the Web GUI or the WinBox.

    Detailed Installation Steps

    Note: the first steps assume you have not enabled container-package and networking on the RouterOS device. If you have, skip ahead to the Setup config-volume step.

    Step 1: Enable Container

    For more information, see MikroTik Container Instructions.

    /system/device-mode/update container=yes

    After this is complete, confirm it is enabled:

    system/device-mode/print
           mode: enterprise
      container: yes

    If you are using the Web or WinBox configuration, you will see a package installed as below:

    c5891755 container installed

    Confirm the container command exists:

    /container/print count-only
    0

    Step 2: Setup container networking

    Now we will enable a virtual Ethernet bridge (veth1) and assign it to the container use. If you wish, you may use direct interfaces without NAT by assigning a second IP, or, by assigning physical ports. Later when the Agilicus connector is installed, it will need to be able to resolve DNS and perform outbound connectivity to api.agilicus.com

    /interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1
    /interface/bridge/add name=dockers
    /ip/address/add address=172.17.0.1/24 interface=dockers
    /interface/bridge/port add bridge=dockers interface=veth1
    /ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24

    Step 3: Confirm sufficient storage space

    Note: Use the internal eMMC if it exists. You will need approximately 100MiB.

    /system/resource/print
     ...
               free-hdd-space: 962.0MiB
              total-hdd-space: 980.0MiB
     ...

    Step 4: Create configuration mount

    Note: the Mikrotik is very fussy about mounts. It must create them itself (rather than being created by e.g. sftp). It will create a magic file called ‘.type’ in the mount dir, do not delete or modify this file.

    /container/mounts/add name=etc_agilicus dst=disk1/etc

    Step 5: Setup image registry

    Note: the cr.agilicus.com/pub/images/agilicus-agent/client:stable image is multi-arch (AMD64, ARM64). If your MikroTik is not one of these, it will not function. If your MikroTik does not support multi-arch containers (e.g. prior to v7.9), you may substitute one of these two tag names:

    • cr.agilicus.com/pub/images/agilicus-agent/client:stable_amd64
    • cr.agilicus.com/pub/images/agilicus-agent/client:stable_arm64
    /container/config/set registry-url=https://cr.agilicus.com tmpdir=/disk1/pull
    /container/add remote-image=pub/images/agilicus-agent/client:stable interface=veth1 root-dir=/disk1/client mounts=etc_agilicus envlist=env_agilicus start-on-boot=yes logging=yes comment=agilicus-connector

    Now lets confirm:

    /container/print detail
     0 ;;; agilicus-connector
       name="fe4a1d62-95b4-479f-95b0-a6aede732c43" tag="pub/images/agilicus-agent/client:stable" os="linux" arch="amd64" interface=veth1 envlist="env_agilicus"
       root-dir=/disk/client mounts=etc_agilicus dns="" start-on-boot=yes status=stopped

    Step 6: Create the config file (on your desktop PC)

    Create a connect as usual in the Resources/Connectors/New screen:

    a48ca0e2 create connector 1

    We will select the ‘Manual’ install and copy the command line. We will make some modifications to it before running.

    d56f534c create connector 2

    Now, create a new empty ‘etc’ directory and cd into it.

    mkdir etc
    cd etc

    Paste the manual install command from above and edit it before hitting enter. The sample line will look like:

    agilicus-agent[suffix] client --install/--kubernetes-install --oidc-issuer https://auth.dbt.agilicus.cloud --org-id XXXXX --agent-id XXXXX

    Modify it to be something like below and then run it. There is no need to be admin/root, this will not install any software, merely create the configuration files. We are just changing the beginning of the command line to be “agilicus-agent client –remote-install”, leave the –oidc-issuer onwards unchanged.

    Note: you will need a local copy of the software on your desktop to create the config file. It does not need to be installed. If you do not have this, you can download the Linux Binary, or the Windows Binary.

    agilicus-agent client --remote-install --oidc-issuer https://auth.YOURISSUER --org-id XXXX --agent-id XXX

    A browser will open to create the Service Account and credentials. The output will look like:

    INFO[2023-03-17T20:14:28-04:00] Starting client - version v0.172.3
    
     You have **2** methods to provide your authentication. Use the most convenient.
     1. You may see a browser open. If you sign in to it, this flow will complete
        automatically, and ignore the url below/paste.
     2. You will see a URL appear here. Cut and paste that into a browser you are
        signed-into. It will then give you a code to paste here.
    
     Typically #1 is used if you are signed into this machine directly, and #2 for
     ssh or remote desktop or embedded devices.
    
    If a browser did not open automatically, please open this link in
    your desktop browser to retrieve the authentication code, and paste below:
    
     https://auth.MYDOMAIN/auth?client_id=XXXXX
    
    Enter verification code: 
    INFO[2023-03-17T20:14:35-04:00] Will install into Will install into directory /tmp/remote-4139368021
    INFO[2023-04-23T12:30:33-04:00] Download root key file
    INFO[2023-04-23T12:30:33-04:00] Fetch agent configuration
    INFO[2023-04-23T12:30:33-04:00] Write agent configuration file in temp directory
    INFO[2023-04-23T12:30:36-04:00] Create connector instance
    INFO[2023-04-23T12:30:36-04:00] creating connector instance
    INFO[2023-04-23T12:30:37-04:00] Join a connector cluster
    INFO[2023-04-23T12:30:37-04:00] Remote installation config created successfully
    INFO[2023-04-23T12:30:37-04:00] Copy <<agent.conf.enc.yaml public_key.json pubring.gpg root.json secring.gpg>> to remote

    At this stage, there should be 4 files in a directory like /tmp/remote-4139368021:

    agent.conf.enc.yaml  public_key.json  pubring.gpg  secring.gpg

    Step 7: Start the Agilicus Connector container

    Note: its important to let the Mikrotik router create the config directory by itself. It creates a ‘magic’ file called .type inside the dir. Without this step, the config directory will be read-only within the container.

    /container/start 0

    After this, check that it is running (and repeat until it is running)

    /container/print detail

    Step 8: Copy the files to the router-os volume:

    scp /tmp/remote-4139368021/* admin@192.168.122.33:/disk1/etc/

    Step 9: Restart container

    Since we copied the config in after letting the container start, we must now restart it.

    /container/stop 1
    (wait until stopped, use /container/print to see)
    /container/start 1

    Step 10: Complete, Checks

    At this stage we are complete. We can perform some diagnostic checks:

    /container/print
     0 ;;; agilicus-connector
       name="fe4a1d62-95b4-479f-95b0-a6aede732c43" tag="pub/images/agilicus-agent/client:stable" os="linux" arch="arm64" interface=veth1 envlist="env_agilicus"
       root-dir=/disk1/client mounts=etc_agilicus dns="" start-on-boot=yes status=running

    You can see the logging and output with the ‘/log/print’ command.

    NOTE

    There is a maximum of 4 instances of a given Connector allowed.

    In the admin web interface, if you see multiple and did not intend, you may need to remove some if you have been iterating on debugging.


  • Agilicus Connector Kubernetes

    Agilicus Connector Kubernetes

    Agilicus Connector Kubernetes

    Kubernetes Connector Install

    Install the Agilicus Connector, via a Container, in your Kubernetes Cluster. Use this to reach local services with no public Ingress.

    Agilicus Connector Kubernetes Install

    connector-install-manual

    The Kubernetes install is intended for advanced usage only. It is for users who are integrating with a larger system. As a pre-requisite, you will need kubectl installed on the machine you will do the installation from.

    The steps initially are similar:

    1. Create a new Connector in admin
    2. Select “Install’
    3. Download the binary (using the alternative manual install, see link for all binaries etc)
    4. Select ‘Manual’. Change –install/–kubernetes-install to –kubernetes-install. Adjust other parameters as needed
    5. The command will output as below.
    6. Inspect the generated YAML, adjust if necessary
    7. Installl with kubectl apply
    $ agilicus-agent client --kubernetes-install  --challenge-id XXXXXX --challenge-code XXXXXX
    INFO[2023-05-30T18:26:47-04:00] Starting connector - version v0.200.6
    INFO[2023-05-30T18:27:00-04:00] creating connector instance
    INFO[2023-05-30T18:27:01-04:00] Join a connector cluster
    INFO[2023-05-30T18:27:01-04:00] Output Kubernetes YAML
    INFO[2023-05-30T18:27:01-04:00] Now run:
    kubectl apply -f /tmp/agilicus-agent-921551629/agilicus-agent.yaml && rm -rf /tmp/agilicus-agent-921551629
    INFO[2023-05-30T18:27:01-04:00]
    INFO[2023-05-30T18:27:01-04:00] Installation Complete
    INFO[2023-05-30T18:27:01-04:00]

    Theory of Operation

    A small (1G) PVC will be created. This will hold the small amount of configuration (service account updates)

    When creating network services, use the same name service resolution you would normally use in Kubernetes (e.g. SERVICE.NAMESPACE)

    A Deployment will be created with replicas=1


  • Connector Install: Ubiquiti EdgeRouter X

    Connector Install: Ubiquiti EdgeRouter X

    b43b8360 ubiquity edgerouter

    Connector Install

    The Ubiquiti EdgeRouter X (ER-X/ER-X SFP) is a small-form factor router. In addition to performing routing services, it is a good vantage point to run the Agilicus Connector if you already have it.

    Connector Install: Ubiquiti EdgeRouter X

    The Ubiquiti EdgeRouter X (ER-X/ER-X SFP) is a small-form factor router. In addition to performing routing services, it is a good vantage point to run the Agilicus Connector.

    (Once you have completed these, you may wish to try accessing the EdgeRouter X web interface via the Agilicus Any-X platform, see example).

    DEVICE WARNING

    Note: this device is a low-performance device with an older processor and low ram. If you have a need for more than a few services, or ones which need more than ~10Mbps of throughput, we recommend a newer device such as NanoPi, a Raspberry Pi, or a pfSense.

    The below instructions were tested on an EdgeRouter X SFP with v2.0.9, specifically:

    # cat /etc/version
    EdgeRouter.ER-e50.v2.0.9-hotfix.2.5402463.210511.1317

    Installation

    In the Agilicus Administrative Web interface, you will:

    1. Create Connector
    2. Copy the install command line
    3. Paste this into the ssh interface of the Ubiquiti EdgeRouter X

    Step 1: Create Connector

    Navigate (in the Agilicus admin web interface) to ‘Resources/Connectors/New’.

    1a53ec15 image

    Step 2: Copy the install command line

    Select “Linux”. Copy the command line to your clipboard. Run on the ssh interface to the ERX.

    This command will fetch a script, and then run it with a time-limited challenge.

    Note: the command line looks complex since it must run on multiple platforms, some of which have curl, some of which have wget, but it effictively fetchs a single install script and runs it with 2 arguments. You may feel free to fetch the script and inspect it, run it manually.

    931b541a image

    You should now be complete.

    A complete log of a successful install is shown below for reference.

    don@machine$ ssh ubnt@172.16.0.13
      _____    _
     | ____|__| | __ _  ___          (c) 2010-2020
     |  _| / _  |/ _  |/ _ \         Ubiquiti Networks, Inc.
     | |__| (_| | (_| |  __/
     |_____\__._|\__. |\___|         https://www.ubnt.com
                 |___/
    
    Welcome to EdgeOS
    
    By logging in, accessing, or using the Ubiquiti product, you
    acknowledge that you have read and understood the Ubiquiti
    License Agreement (available in the Web UI at, by default,
    http://192.168.1.1) and agree to be bound by its terms.
    
    ubnt@172.16.0.13's password:
    Linux erx 4.14.54-UBNT #1 SMP Tue May 11 13:23:28 UTC 2021 mips
    Welcome to EdgeOS
    Last login: Sat May 28 18:11:43 2022 from 172.16.0.8
    ubnt@erx:~$ sudo su -
    root@erx:~# which curl && (curl -sL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh); sh /tmp/i.sh JX2EXXXXXXXXXXXXEU https://auth.MYDOMAIN
    /usr/bin/curl
    Starting install... <JX2EXXXXXXXXXXXXEU> <https://auth.MYDOMAIN>
    OS: <Linux>, Machine: <mips>, END: <le>
    INFO[2022-05-28T18:32:33.787560338Z] Starting client - version v0.119.0
    INFO[2022-05-28T18:32:34.923316902Z] Logging in...
    
     You may see a browser open, in which case you may sign in automatically.
     Failing that, if this machine is headless, or remote, you will see a URL below.
     Copy and paste that into a browser you are logged into. You will then see a code,
     paste it in below.
    
    Please go to the following link in your browser to retrieve the authentication
    code:
    	https://auth.MYDOMAIN/auth?client_id=agilicus-builtin-agent-connector&code_challenge=XXXXX&code_challenge_method=S256&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&scope=openid+profile+email+offline_access+urn%3Aagilicus%3Aapi%3Aapplications%3Areader%3F+urn%3Aagilicus%3Aapi%3Aapplications%3Aowner%3F+urn%3Aagilicus%3Aapi%3Atraffic-tokens%3Aowner+urn%3Aagilicus%3Aapplication_service%3A%2A%3Aowner%3F&state=XXXXX
    
    Enter verification code: scpfcXXXXXpim4qq5pl
    checking code
    INFO[2022-05-28T18:33:23.875526942Z] Check if the agilicus-agent is already running as a service. If so stop it
    INFO[2022-05-28T18:33:23.932589295Z] Create a directory at /etc/agilicus/agent
    INFO[2022-05-28T18:33:23.934868328Z] Download public key file to /etc/agilicus/agent/public_key.json
    INFO[2022-05-28T18:33:24.265979606Z] Create file /usr/bin/agilicus-agent-wrapper.sh
    INFO[2022-05-28T18:33:24.266562921Z] Create file /etc/systemd/system/agilicus-agent.service
    INFO[2022-05-28T18:33:24.273604799Z] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x}
    INFO[2022-05-28T18:33:24.278649712Z] Will install to /agilicus-agent.service -> {/etc/systemd/system/agilicus-agent.service -r--r--r--}
    INFO[2022-05-28T18:33:24.282177117Z] Create a directory at /opt/agilicus/agent/tufmetadata/latest
    INFO[2022-05-28T18:33:24.282578531Z] Create a directory at /opt/agilicus/agent/tufmetadata/stable
    INFO[2022-05-28T18:33:24.285506591Z] Setup Agilicus secure store
    INFO[2022-05-28T18:33:24.285945878Z] Create secure keyring for storing communication credentials in /etc/agilicus/agent
    INFO[2022-05-28T18:34:25.392134745Z] Fetch agent configuration
    INFO[2022-05-28T18:34:25.392429467Z] Write agent configuration file in /etc/agilicus/agent/agent.conf.enc.yaml
    INFO[2022-05-28T18:34:26.432424427Z] Create a user and group named Agilicus to run the agilicus-agent service
    INFO[2022-05-28T18:34:26.432722016Z] Copy executable to /opt/agilicus/agent
    INFO[2022-05-28T18:34:26.432866291Z] Set permissions to Agilicus on /opt/agilicus/agent
    INFO[2022-05-28T18:34:26.433163321Z] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent-mipsle
    INFO[2022-05-28T18:34:26.914492417Z] Start agilicus-agent service
    INFO[2022-05-28T18:34:27.898994929Z] Installation Complete
    root@erx:~# systemctl status agilicus-agent.service
    * agilicus-agent.service - Agilicus Agent
       Loaded: loaded (/etc/systemd/system/agilicus-agent.service; enabled; vendor preset: enabled)
       Active: active (running) since Sat 2022-05-28 18:34:27 UTC; 9s ago
     Main PID: 23147 (agilicus-agent)
       CGroup: /system.slice/agilicus-agent.service
               `-23147 /usr/bin/agilicus-agent client --cfg-file /etc/agilicus/agent/agent.conf.enc.yaml

    Note: Missing Let’s Encrypt Intermediary

    curl -k https://letsencrypt.org/certs/lets-encrypt-r3.pem -o /etc/ssl/certs/lets-encrypt-r3.pem
    sed -i ‘/^mozilla\/DST_Root_CA_X3/s/^/!/’ /etc/ca-certificates.conf
    update-ca-certificates

    Note: Time Synchronisation (NTP)

    Before running the install steps, ensure NTP (time synchronisation) is running. If you do not have your own NTP server, use pool.ntp.org (specifically, use 0.pool.ntp.org as a server name). NTP can be enabled in the ‘system’ menu.


  • Agilicus Connector in Private VPC In AWS EC2

    Agilicus Connector in Private VPC In AWS EC2

    24a022e5 cloud

    Agilicus Connector in Private VPC In AWS EC2

    You have a Virtual Private Cloud (VPC) in AWS EC2. It has private-only IP addressing. You need to ssh to some hosts within it, or remote desktop, or share some folders, etc. In this example we will show how to install the Agilicus Connector onto a t2.micro instance, with no public IP (and no NAT Gateway), and, use that to reach other instances within the VPC directly. There is no routing, no inbound or outbound connectivity otherwise.

    Overview

    You have a Virtual Private Cloud (VPC) in AWS EC2. It has private-only IP addressing. You need to ssh to some hosts within it, or remote desktop, or share some folders, etc. In this example we will show how to install the Agilicus Connector onto a t2.micro instance, with no public IP (and no NAT Gateway), and, use that to reach other instances within the VPC directly. There is no routing, no inbound or outbound connectivity otherwise.

    Note: you can also follow these instructions AWS Doc to install a NAT gateway into your VPC, and then install the Agilicus Connector on a single machine within the VPC. This would allow your other VPC components to reach outbound.

    In this example we will show a setup where a dual-homed t2.micro

    0aebdc04 agilicus agent aws.drawio

    Step 1: Create Private VPC

    For this demonstration the private VPC has no NAT gateway, no Internet access. This is an internal only network. You can decide whether it has onwards access to other Amazon services if needed.

    cd0510bd image

    Step 3: Create private EC2 Server

    For demonstration purposes we create an EC2 server to ssh to.

    58f82ddf image

    cd45307f image

    Step 4: Create dual-homed EC2 instance for Agilicus Connector

    This machine will act to straddle the private VPC and the public Internet. It does not route, it does not NAT. No traffic will flow from/to it without going through the Agilicus Identity-Aware Firewall.

    a83b9a6f image
    fefe6b64 image

    OK at this stage we have a VPC with no public IP. We have a private server on it with no public IP. We have a 2nd server, with a public IP, that can reach the devices in the VPC. We will now install the Agilicus Connector to facility onwards ssh.

    Now, if we look at the config of the private server, we can see its hostname and IP:

    03fe7e5c image

    Step 5: Install Agilicus Connector

    These instructions are as normal for a Linux host. We create the connector in the web front end, it gives us a command line to run.

    1a53ec15 image

    We are now given a command line to run. We paste it into the ssh on the Agilicus Gateway server (the one with the public IP):

    At this stage we are done, and ready to create an SSH resource in the Agilicus Admin GUI. We do this as normal.

    Now open Agilicus Launcher and observe we can ssh to the ec2-private server, both from the Web interface, and, from our desktop.

    If desired, enter a manual ~/.ssh/config entry to override the private key

    At this stage we are done. We can ssh directly there:

  • Synology Connector Install

    Synology Connector Install

    Synology SSH Enable

    Synology Connector Install

    Synology NAS. Agilicus Connector.

    Overview

    The Agilicus Connector can install on an embedded NAS product such as Synology. The devices (usually) have either an Intel or an Arm processor. The instructions are the same for each, but the link is different. The instructions below are for a Synology NAS but will be similar on other devices.

    NOTE: Upgrades

    Note: it is possible that when you upgrade the OS to your Synology you may need to re-install your Agilicus Connector.

    No changes are needed to your firewall. No VPN is needed. You can administer users via their Active Directory or Apple, Google, Linkedin accounts.

    The high level steps are:

    1. Enable SSH on your NAS
    2. Create a Connector (Agilicus admin interface)
    3. SSH to the NAS
    4. Run the given command

    after this, the Agilicus Connector will be entirely automatic, and controlled via the Agilicus admin interface.

    Synology SSH Enable

    1. Enable SSH

    In order to install the Agilicus Connector on your Synology NAS, you will first need to enable SSH. We can do this from the Synology Web Interface Control Panel, select “Terminal & SNMP” under Applications.

    If you are not familiar with SSH, it is a Secure Shell remote command line interface. We will only use it for the installation step here, after which we don’t need it. You may use ssh from the command line on your Windows, Mac, Linux machine (it is typically installed on all of these). You may also use Putty, or, you may install SSH into Chrome and use from your browser.

    2. Create Agilicus Connector

    First we will create a Connector. This logical endpoint allows reverse inbound connectors to safely occur.

    We give the connector a name. This is used for statistics and diagnostics purposes.

    1a53ec15 image
    8bb13105 image

    You will now be presented with some download instructions. Copy the command line given for Linux.

    3. SSH to the NAS

    SSH to your NAS. Run ‘sudo -i’. Now paste the command line

    ...
    INFO[2024-01-07T17:14:35-05:00] Starting connector - version v0.237.1
    INFO[2024-01-07T17:15:00-05:00] Check if the agilicus connector is already running as a service. If so stop it
    ...
    INFO[2024-01-07T17:15:09-05:00] creating connector instance
    INFO[2024-01-07T17:15:10-05:00] Join a connector cluster
    INFO[2024-01-07T17:15:10-05:00] Start agilicus-agent service
    INFO[2024-01-07T17:15:18-05:00]
    INFO[2024-01-07T17:15:18-05:00] Installation Complete
    

    At this stage we are complete. Let us look at some sample first resources.

    Sample: Synology Web Interface

    As a first example, let us make the Synology Web interface available via Agilicus. The detailed screen shots are below, but the steps are:

    1. Resources/Application New. Select a name (this will become an internet host name, so it cannot have spaces or special characters)
    2. Select which connector (the one we just installed) is on the same site as the Synology
    3. Select the network coordinates of the Synology web interface. Since we are running inside the NAS, we can use ‘localhost’ and 5000 for a port (these are the internal coordinates of the web interface)
    4. Select authenticated by Proxy. This means a user will be forced to provide credentials in order to see the web interface
    5. Select ‘named users, single role’, we will assign permissions in the next step. Hit apply, this will create the application.
    6. Assign permissions. Access/Application Permissions. We can assign permissions to groups or individual users. Select the row for the user/group, and the column for the application.
    7. We are done. Let’s test. We can use ‘profile’ (https://profile.YOURDOMAIN), or, directly, https://APPNAME.YOURDOMAIN. let’s use the link to profile in the lower left, note (and bookmark) the URL it goes to.
    8. You should see an icon for your new Synology NAS web interface. If not, refresh the page. If you select it, it will navigate to a new web page, note the URL.
    d61c1ba6 image
    0888269d image
    4494d171 image
    9cedce05 image
    e975e33e image
    8149d6a6 image
    607d42a5 image
    9c7e9dd4 image
    08a451f5 image
    7507cf47 image

    Sample: Synology Share

    Let’s assume we have a Share existing on our Synology called ‘tmp’. On the filesystem this is in /volume1/tmp. Once we have completed the above steps, we can create a new Share in the Agilicus admin interface (https://admin.YOURDOMAIN).

    0ef3e0f3 create share

    Next we will be asked for two parameters (web uri path prefix, name). The first will appear in an http path, e.g. if you say “bobcat”, the URI your users will see is https://files.YOURDOMAIN/bobcat. The second is a name which will show up in the audit log. Normally these are the same (unless you have the same share name on multiple hosts).

    Share Name

    Now we will indicate the path on the Synology. In our example (The synology has a share called tmp, this will be in /volume1/tmp)

    Share Path

    At this stage you will be given the option to test this in the administrative interface, and, your users may navigate to https://profile.MYDOMAIN to get their own mount instructions for their desktops.

    Sample: Synology Surveillance Station Remote Cameras

    See Synology Surveillance Station for detailed setup, the above web interface setup will give you access to your cameras, the remainder of the setup is on the NAS interface.

    Uninstall

  • Agilicus Connector Windows Cluster

    Agilicus Connector Windows Cluster

    cluster

    Windows Cluster

    The Agilicus Connector supports native high-availability. In some environments (notably Windows High Availbility File Servers), it may be desirable to instead use Microsoft’s Windows Clustering technology.

    Agilicus Connector Windows Cluster

    To enable High Availability in the Agilicus Connector in a Windows environment (e.g. for resilient access to a Share, to remote desktops), configure it within a Windows Failover cluster.

    The high level instructions are:

    1. configure a windows failover cluster with a shared disk of at least 200MiB.
    2. Install the Agilicus Connector into the shared disk on one of the servers. See below for specific instruction.
    3. Stop the service on the node and set it to Disabled
    4. Open the failover cluster manager
    5. In your cluster, select Roles-> add new roles
    6. Click next, select the “Generic Application” role
    7. For the command line, enter F:\agilicus-agent.exe (the working directory from the install instructions, the shared disk)
    8. name the service something unique (e.g. “agilicus-connector”)
    9. Add the storage (e.g. F: in our example)
    10. Don’t register settings
    11. Click confirm, finish
    12. Verify the Agilicus connector is running
    21421bcc image
    b3def478 image
    3c7874f4 image
    1aefac83 image
    f93129f0 image
    c5012e81 image

    Connector Install

    On one of the servers in the cluster, we will perform the install as normal, with one modification.

    Open a browser (on any machine, does not need to be the windows cluster), sign in to the Agilicus Admin web interface, create a new connector, select the appropriate OS tab, and copy.

    On the machine in the server cluster, open an administrative shell, paste the command line. DO NOT PRESS ENTER. Add a command line parameter of ‘–working-directory <PATH>’ where <PATH> is the shared folder (e.g. F:\Agilicus).

    For cmd, the sample command would then look something like below:

    curl -sSL -o %TEMP%\aa.exe agilicus.com/www/releases/secure-agent/stable/agilicus-agent.exe && %TEMP%\aa.exe client --install --working-directory F:\Agilicus --challenge-id xxxxxxxxxxxx --challenge-code xxxxxx --debug  && del %TEMP%\aa.exe
    7b4c8574 image
    531231d0 image

    Like Share Warning

    If you add a Share, ensure that both paths map to the same resource. E.g. ensure that X:\foo is the same on both machines if you will export X:\foo

    1452b7ee screenshot from 2021 10 04 22 25 48
    5841f1cc screenshot from 2021 10 04 22 26 23
    80224d15 screenshot from 2021 10 04 22 29 25
  • Linux, FreeBSD, Embedded Connector Install

    Linux, FreeBSD, Embedded Connector Install

    teach

    Linux, FreeBSD, Embedded

    The Agilicus Connector runs natively on most Linux or FreeBSD platforms. These might be embedded, or servers.

    Linux, FreeBSD, Embedded Connector Install

    The instructions to install the Agilicus Connector are nearly identical on various Unix operating systems. This includes desktops, servers, and embedded devices.

    See a specific example, the NanoPI R5S or a Synology NAS. Most platforms are installed as follows:

    Create Agilicus Connector

    First we will create a Connector. This logical endpoint allows reverse inbound connectors to safely occur.

    We give the connector a name. This is used for statistics and diagnostics purposes.

    1a53ec15 image
    8bb13105 image

    You will now be presented with some download instructions. Copy the command line given for Linux.

    SSH to the device

    SSH to your device. Run ‘sudo -i’ if you are not root (your prompt is not ‘#’). Now paste the command line

    ...
    INFO[2024-01-07T17:14:35-05:00] Starting connector - version v0.237.1
    INFO[2024-01-07T17:15:00-05:00] Check if the agilicus connector is already running as a service. If so stop it
    ...
    INFO[2024-01-07T17:15:09-05:00] creating connector instance
    INFO[2024-01-07T17:15:10-05:00] Join a connector cluster
    INFO[2024-01-07T17:15:10-05:00] Start agilicus-agent service
    INFO[2024-01-07T17:15:18-05:00]
    INFO[2024-01-07T17:15:18-05:00] Installation Complete
    

    At this stage we are complete.

    General Devices

    Generically supported are any devices running Linux with at least 256MiB of RAM, at least 512MiB of flash storage, ARM or x86 processor. These include below (and more).

    • systemd-based Linux installations (e.g. Ubuntu etc)
    • upstart-based Linux installations
    • Raspberry PI
    • OpenWRT
    • pfSense (FreeBSD Firewall)
    • Ubiquity Edge Router X
    • Synology NAS

    Specific walk-throughs are provided for some of these on the Agilicus Connector page.

  • Sample Ubiquiti EdgeRouter-X EdgeMax Web Interface

    Sample Ubiquiti EdgeRouter-X EdgeMax Web Interface

    cyber-insurance-compliance

    Ubiquiti EdgeRouter-X EdgeMax

    The Ubiquiti EdgeRouter-X has a built in web interface. In this example, we use a connector installed on it to make this web interface available to arbitrary users over the public Internet

    Overview

    The Ubiquiti EdgeRouter-X has a built in web interface. In this example, we use a connector installed on it to make this web interface available to arbitrary users over the public Internet… without opening the firewall. Each user must use Single-Sign-On via Agilicus plus their existing identity provider, and then can access from any device without a VPN.

    Step 1. Create application

    f0955160 image

    Step 2. Enter name (hostname we will use externally), description

    b96b0b41 image

    Step 3. Indicate we use standard pattern hostname.

    a4aa0a42 image

    Step 4. Indicate its via an Agilicus Connector (in this case, installed on the Ubiquiti EdgeRouter-X directly).

    728bf784 image

    Step 5. Select the connector (previously configured as per instructions)

    242c337c image

    Step 6. Indicate we will use TLS from user to device.

    ffa0ea9b image

    Step 6. Configure upstream as localhost:443, on TLS (this is the local web server of the EdgeRouter)

    9ab570a3 image

    Step 7. Indicate that Agilicus will do an OpenID Connect Authentication Proxy, use /logout as the revoke token URI.

    328ab3a1 image

    Step 8. Indicate that we will have individual users.

    eece247e image

    Step 9. Apply. After this is complete we will then add a user to permissions and test.

    cc8ac07b image

    At this stage we can assign permissions:

    e45db7e8 image

    Now we can either use profile (https://profile.MYDOMAIN) which has all applications in it as a launcher, or navigate directly (https://erx.MYDOMAIN).

    d5dee728 image

    If desired, publish so that it is selectable in profile, and give it an icon:

    eafc2f89 image
  • Connector Install: Raspberry Pi

    Connector Install: Raspberry Pi

    ae2c7d35 raspberry pi

    Raspberry Pi

    Overview

    Modular single board computers (such as a Raspberry Pi) makes an excellent platform to run the Agilicus Connector.

    The below instructions were tested on a Raspberry Pi 4, specifically:

    # cat /etc/debian_version
    10.12
    # cat /etc/os-release
    PRETTY_NAME="Raspbian GNU/Linux 10 (buster)"
    NAME="Raspbian GNU/Linux"
    VERSION_ID="10"
    VERSION="10 (buster)"
    VERSION_CODENAME=buster
    ID=raspbian
    ID_LIKE=debian
    HOME_URL="http://www.raspbian.org/"
    SUPPORT_URL="http://www.raspbian.org/RaspbianForums"
    BUG_REPORT_URL="http://www.raspbian.org/RaspbianBugs"

    During the installation, a Service Account will be created (permissions for the Connector to run as).

    The Raspberry Pi installation uses the same instructions as the Linux ones (image at right) A sample command line is offered in the Agilicus admin porttal, which may be pasted into the ssh shell.

    You are now complete.

    Logs (if any) are generated to /var/log/agilicus-agent.log (e.g. run ‘tail -F /var/log/agilicus-agent.log’)

    We may check the status once installed as below.

    Sample Install Output

    RPI $ which curl && (curl -sSL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh); sh /tmp/i.sh -c hAS43XdGbJwpnmSo2AjrKH -s ua6keppv
    /usr/bin/curl
    Must run as root to do install, attempting to use sudo.
    OS: <Linux>, Machine: <x86_64>, END: <le>
    Fetching https://www.agilicus.com/www/releases/secure-agent/stable/agilicus-agent into /tmp/agilicus-agent
    -rwxr-xr-x 1 root root 50616688 Jul  1 18:12 /tmp/agilicus-agent
    + /tmp/agilicus-agent client --install --challenge-id hAS43XdGbJwpnmSo2AjrKH --challenge-code ua6keppv
    INFO[2023-07-01T18:12:16-04:00] Starting connector - version v0.208.3
    INFO[2023-07-01T18:12:30-04:00] Check if the agilicus connector is already running as a service. If so stop it
    INFO[2023-07-01T18:12:30-04:00] Create file /usr/bin/agilicus-agent-wrapper.sh
    INFO[2023-07-01T18:12:30-04:00] Create file /etc/systemd/system/agilicus-agent.service
    INFO[2023-07-01T18:12:30-04:00] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x <nil>}
    INFO[2023-07-01T18:12:30-04:00] Will install to /agilicus-agent.service -> {/etc/systemd/system/agilicus-agent.service -r--r--r-- 0x135ad20}
    INFO[2023-07-01T18:12:30-04:00] Create a directory at /opt/agilicus/agent/tufmetadata/latest
    INFO[2023-07-01T18:12:30-04:00] Create a directory at /opt/agilicus/agent/tufmetadata/stable
    INFO[2023-07-01T18:12:30-04:00] Create a user and group named Agilicus to run the agilicus-agent service
    INFO[2023-07-01T18:12:30-04:00] Copy executable to /opt/agilicus/agent
    INFO[2023-07-01T18:12:30-04:00] Set permissions to Agilicus on /opt/agilicus/agent
    INFO[2023-07-01T18:12:30-04:00] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent
    INFO[2023-07-01T18:12:31-04:00] creating connector instance
    INFO[2023-07-01T18:12:31-04:00] Join a connector cluster
    INFO[2023-07-01T18:12:31-04:00] Start agilicus-agent service
    INFO[2023-07-01T18:12:32-04:00]
    INFO[2023-07-01T18:12:32-04:00] Installation Complete
    INFO[2023-07-01T18:12:32-04:00]
    RPI $

  • Connector Install: Netgate SG-1100 pfSense

    Connector Install: Netgate SG-1100 pfSense

    56783352 sg 1100

    Netgate SG-1100 pfSense

    The Netgate SG-1100 pfSense is a small-form factor router. it is a good vantage point to run the Agilicus Connector.

    Agent Connector Install: Netgate SG-1100 pfSense

    The Netgate SG-1100 pfSense is a small-form factor router. it is a good vantage point to run the Agilicus Connector.

    Other pfSense appliances may work, they will need to be arm or x86 based, and have at least 120MiB of storage available. The Agilicus connector will consume approximately 50MiB of RAM.

    The below instructions were tested on a Netgate SG-1100 with v22.01, specifically:

    The pfSense installation uses the same instructions as the Linux ones (image at right) A sample command line is offered in the Agilicus admin porttal, which may be pasted into the ssh shell.

    Once you run this command, you will see output as below. You are now complete.

    The Agilicus Agent Connector will self-update over time, no intervention is required.

    We may check the status once installed as below.

    Logs (if any) are generated to /var/log/agilicus-agent.log (e.g. run ‘tail -F /var/log/agilicus-agent.log’)

    Sample Install Log

    The complete log of a sample install is below.

    NOTE: if you use the connector as a means of getting to the local admin web interface, you may see an error such as “An HTTP_REFERER was detected other than what is defined in System > Advanced (https://pfsense-web.dbt.agilicus.cloud/index.php). If not needed, this check can be disabled in System > Advanced > Admin Access.
    To work around this, run this command pfSsh.php playback disablereferercheck.


  • Agilicus Connector – NanoPI R5S

    Agilicus Connector – NanoPI R5S

    nanopi-r5s

    Agilicus Connector – NanoPI R5S

    NanoPi R5S Background

    The NanoPI R5S has 1 x Gigabit Ethernet, 2 x 2.5 Gigabit Ethernet, 4GiB of RAM, and 32GB of eMMC storage. With its large passive heatsink it is an ideal platform to use as a small router. It also makes an ideal platform to run the Agilicus Connector.

    The NanoPi R5S will run several operating systems (Ubuntu, Armbian, OpenWRT). In this document we discuss using it with OpenWRT. Specifically, Agilicus makes available a hardened-version of OpenWRT for this platform.

    Installing Agilicus OpenWRT

    As received, the NanoPi R5S will (usually) be running FriendlyWRT. You may feel free to use this, however it has some security flaws. Agilicus recommends using our build. You may build it yourself, or for convenience we supply an image here.

    267cb5d7 image
    1. Connect your laptop to one of the two LAN ports (closest to the USB-C power connector).
    2. Open a browser to http://192.168.2.1/
    3. Sign in as ‘root’, password ‘password’
    4. Select ‘System/eMMC Tools’
    5. Download openwrt-rockchip-armv8-friendlyarm_nanopi-r5s-squashfs-sysupgrade.img.gz (previous release)
    6. Select ‘Choose File’. Select the file you downloaded
    7. Select ‘Upload and Write’
    8. Wait approximately 90s (until the lights stop flashing and it indicates its complete)
    9. Power off, power on

    At this stage you are running the Agilicus-supplied OpenWRT image.

    2e822959 image
    7999e14d image
    d95df461 image
    4905dfb9 image

    Router Setup

    c49ee8a2 image

    We have chosen to disable DHCP server by default (to avoid the risk of plugging this device into an existing network and causing confusion). To initially connect, plug your laptop into one of the LAN ports (closest to the USB-C connector) and set the IP on your laptop to ‘192.168.2.2’ and connect to http://192.168.2.1/ via your browser.

    On first sign-in, you will be prompted to set a password. Choose something strong (later we will suggest a way that the router is blocked for password access entirely).

    This is a standard OpenWRT (23.04) image, and the normal User Guides show different configuration options.

    The default configuration is:

    No UPnP services nor mDNS/Avahi are enabled by default.

    Agilicus Connector Install

    Using the Agilicus administrative portal, create a new connector. Use the ‘Linux’ instructions, copy.

    In the OpenWRT admin interface (http://192.168.2.1/), select ‘Services/Terminal’. Sign in as root and the password you selected. Paste (shift-insert).

    At this time the connector should be installed and you may close the terminal.

    24b5a7dc image
    8bfda54e image

    You may wish to enable access to this router via the Agilicus AnyX platform (notably SSH and Admin web interface).

    NOTE: DHCP Server Enable

    Depending on your use, you may wish to have a DHCP server on the LAN ports, you can enable this under ‘Network/Interfaces/LAN’. You may also configure your desired IP range here.

    It is appropriate to have a DHCP server on these LAN ports if this is an isolated network. If you are connecting to a larger network with an existing DHCP server, you probably wish to instead change the protocol on the LAN ports to DHCP Client.

    3a0fb06e image
    1e4619ff image

    NOTE: Time Sync (NTP)

    Modern cryptography requires clock sync and accuracy on all devices. Typically this is performed via Network Time Protocol, however, in some environments this is blocked (e.g. HTTPS-only outbound).

    If your clock is not sync’d (see System/Time Synchronisation menu), you might be able to use a local NTP server. If not, you can enable an HTTPS-based sync as below:

    This is going to use the Agilicus API to provide an HTTP-based (over HTTPS port 443) time service. Configuration can be observed in /etc/config/htpdate:

    Security Hardening

    Web Terminal Disable

    f00fff0e image

    Once you have installed the Agilicus Connector, we recommend disabling the web terminal. On ‘Services/Termina’, select the config tab and remove the check-box beside ‘Enable’.

    You may re-enable the web terminal later if you need it. However, we recommend using SSH instead for future command-line access.

    The web terminal operates on a secondary TCP port (7681) and is not needed for normal operation.

    SSH Setup

    94a026d2 image

    Agilicus recommends disabling password access to SSH in favour of SSH Keys.

    On System/Administration, the SSH Access tab, uncheck ‘Password authentication’ and uncheck ‘Allow root logins with password’.

    The rationale here is that password stuffing and guessing is a thing. Eventually someone will guess your l33t-hax0r password. Removing any ability to use passwords reduces the risk. In some controls environments any passwords can be disallowed.

    dc2dee2c image

    Once you have disabled password access, we recommend adding a SSH Key. Agilicus recommends using ed25519 SSH keys since they are smaller and more secure. Add your public key to the router here and place the private key (with passphrase!) in your SSH Agent on your desktop.

    SSH keys are not only more secure, but also more convenient.

    One downside to note: the Agilicus web interface for SSH is not currently compatible with SSH keys. If you wish to have SSH access to this device via the Agilicus Profile web interface, keep password on.

    Firewall

    At this stage, configure the firewall and NAT settings to suit on each of the interfaces. If the Agilicus Connector is providing Service Forwarder services, remember to open this ports on the router too.

    We can check which ports are listening by running netstat -nlpt as below. Things with 0.0.0.0:PORT are available from outside the device. Things listening on 127.0.0.1, fe80::, ::1, etc, are locally bound only. In the example below, ‘uhttpd’ (the admin web interface), ‘dropbear’ (SSH) and ‘ttyd’ (the web terminal) are the only things listening.


    Sample Configuration: Connect to Local HTTP + SSH

    This walk through shows an example of how, once the connector is installed (as per above), configuration of an HTTP and SSH interface to this local device. Once these are configured you could use the firewall to disable all external access. The high level steps are:

    1. Create Connector (Agilicus Admin)
    2. Install Connector (NanoPi Web Terminal)
    3. Create SSH Resource (Agilicus Admin)
    4. Create Web Resource (Agilicus Admin)
    5. Assign Web Resource Permission (Agilicus Admin)
    6. SSH to NanoPi from Agilicus Profile (Agilicus Profile)
    7. Open Web Interface to NanoPi (Agilicus Profile or direct)

    OK, let’s get started. This will take approximately 5 minutes.

    e221ad7b image

    First, create the connector on the NanoPi. Skip this is you have already done so above.

    4cd84b15 image

    Select install. On the dialog, select ‘Linux’. Select ‘Copy’

    0507393e image

    On the NanoPi web interface, open the terminal, sign in. Press ‘Shift-Insert’ to paste the line you copied above.

    22ce94af image

    You should see output as to the left, taking about 30 seconds.

    Errors you might see include:

    • Time issues. The NanoPi does not have a battery-backed real-time clock. It is setup to use Network Time Protocol (NTP). If your firewall blocks this, or the WAN port is not connected, you must solve this first. Cryptography and certificates require good time sync. See below for an https-only solution that is simple to firewall.
    • Outbound firewall blocking www.agilicus.com or api.agilicus.com (both on port 443)

    At this stage the connector is installed on this device. We will move on and configure SSH access next.

    c5156c74 image

    Create a new SSH resource. Select the connector we created above.

    c5156c74 image

    Create a new SSH resource. Select the connector we created above.

    7fa92adc image

    Give the SSH resource a name. We will see this later in the Web Interface and from the command line. The name must be valid as a hostname (e.g. no spaces).

    e586c74a image

    Assign permissions. For this sample, we are assigning permissions to a single user. More commonly one would create a group (e.g. SSH Admins) to simplify.


    At this stage, we have finished the SSH setup. We can use it from the Agilicus Profile (web-based, any device), from the Start menu on a desktop operating system, or via the command-line on our desktop. It will work with Putty and OpenSSH.

    Now let us configure a Web Application to see the web console of the NanoPi R5S.

    80554db0 image

    Create a new application. Give it a name (which must be valid as a hostname in format). You will later be accessing this as https://NAME.DOMAIN/

    dc047beb image

    You may, if you wish, have a well-known alias to this new web interface. This is more commonly done with very public ones (e.g. a Wiki or Timesheet system). Leave it as default and the Agilicus AnyX will create the hostname for you.

    afafc5e5 image

    Select the connector from the previous step.

    f9075bc3 image

    The connector has to know where to send the request (it is a proxy). The ‘upstream’ in this case is the NanoPi R5S itself, e.g. localhost port 80.

    b1a2f5be image

    For a bit of additional security we can tie the ‘logout’ URL of the NanoPi R5S web interface to the Agilicus AnyX logout by copying in the URL of the logout. This is optional.

    We also suggest that named users with a single role, configured later, for this sample. Normally you would create a group, e.g. ‘Web Admins’ and assign users to it.

    At this stage we are done, select ‘Apply’.

    4bd7f6d0 image

    Now we will assign ourselves permission to use this new web resource.

    7de48b4f image

    To make the profile a bit more ‘fun’ we can now assign a logo (an icon) to the launch of this web interface. In this ‘define’ section we could also refine the Web Application Firewall rules etc.

    43727b23 image

    Any image file (we suggest about 512×512) is suitable for a logo.

    At this stage we are done. We have:

    1. created and installed a connector on this NanoPi R5S.
    2. created an SSH service (to the NanoPi itself)
    3. created a Web resource (to the NanoPi itself)

    We can now test our work. Open https://profile.YOURDOMAIN/

    ccd9d640 image

    Once you have signed in, you will see an icon for the new web resource, if you click it, a new browser tab will open. Observe the URL (https://NAME.DOMAIN). You can use this directly without profile if you wish. If you sign in, you will see the NanoPi R5S web interface directly. Now try it from a different network (e.g. your mobile phone, disable WiFi). Observe you can still connect. Now try with an unprivileged user (e.g. a different Gmail account), observe you cannot sign in.

    The ‘profile’ interface acts as a launch pad for the end-user. It will act as a Progressive Web Application (e.g. ‘add to homescreen’ on your mobile), giving you a single launch icon.

    You may also use the resources it points to directly: it is your choice.

    50b7155e image
    d7026aad image

    We can test the SSH access. From profile, select the resource we created earlier.

    We will see a ‘login’ dialog appear, enter the username (root) and password to the NanoPi R5S.

    At this stage, we should see an SSH terminal.

    From here, consider using the ‘Launcher’ install feature of profile, add the Browser Extension. You will now see an entry on your start menu for this SSH, opening the native client (e.g. if you have Putty or OpenSSH installed).

    Similarly to the Web Resource, only users with permission are able to sign in. You may also choose to enable multi-factor authentication on your user and observe how this functions with both Web and SSH resources.


  • Agilicus Connector

    Agilicus Connector

    Agilicus Connector

    Agilicus Connector

    The Agilicus Connector facilitates connection from a bastion network and end-users. It installs on a device somewhere inside the protected network, making an outbound connection.

    Agilicus Connector Overview

    The Agilicus Connector facilitates connection from a bastion network and end-users. It installs on a device somewhere inside the protected network, making an outbound connection.

    If you are new to the system, you may try a full ‘demo’ setup with your own connector in a virtual enviroment in our system, with no install. See “Agilicus AnyX Demo“. When you ‘create a connector’ it will offer you a ‘demo’ this will create a new virtual environment to test in with no isntall, no obligation.

    The Connector is self-updating. Once installed it will stay up to date. The live Changelog shows the updates that have occurred.

    Connectors facilitate:

    • shares [must have local access to the files)
    • Web Applications (must have onward connectivity)
    • Local authentication
    • Network resources (e.g. SSH, Remote Desktop, VNC)

    Theory of Operation

    The Agilicus Connector creates an outbound connection, using HTTPS, to the Agilicus AnyX Cloud. This persistent connection is then used to route individual user requests back in to the appropriate resource.

    Each individual inbound request first has the user identity checked (authentication), then has the user’s role (authorisation) checked, prior to being routed inwards.

    The net affect is that no traffic arrives at the protected resources unless it is for:

    • An authenticated user (optionally with multifactor authentication)
    • An authorised action (e.g. can the user edit the wiki)
    • A valid resource

    This is a very strong guarantee, and, achieved without complex (or any) firewall rules.

    The use of industry-standard HTTPS and WebSocket means inspecting firewalls such as Zscaler or PaloAlto can be used in the path.

    If we expand the data flow for a hypothetical SSH client with animation, we will see the WebSocket flows (blue) establish, and then the ssh flow. The SSH flow is delivered from User to SSH server encrypted end-to-end: the host key is maintained intact.

    SSH Animated Data Flow
    SSH Animated Data Flow

    High Availability Option

    The Agilicus Connector supports high availability (resiliency), either natively, or, via Windows Clustering. See High Availability installation for more information.

    Installation

    Installation of the connector is very simple: 3 steps.

    First, create (Admin console: Resources/Connectors/New)

    Second, name (a name that means something, must be a valid hostname. E.g. the machine it is installed on, the site it connects, etc)

    Third, install (paste the command on the target machine)

    Once installed, the connector will keep itself up to date using The Update Framework.

    During the creation of the Connector you will give it a name. This name should have some meaning for you, e.g. the site it is installed in, the host it is installed on, etc. We recommend it be the hostname that is running the Connector.

    At this stage you will see a dialog giving installation instructions. At the top are 3 tabs (Linux, Windows-CMD, Windows-PowerShell).

    eec3f30e image
    connector-install-manual

    The Linux tab should work on most Linux or FreeBSD-derived hosts, including pfSense, OpenWRT, Ubuntu, Debian, Synology, etc.

    On a Windows host it does not matter which of the two instruction you follow, they will lead to the same result. Typically you will use the ‘cmd‘ instructions.

    In all 3 cases, copy the text box (using the blue-button at the bottom right) and paste it into an administrative shell.

    Uninstall / Delete

    When you no longer need an Agilicus Connector, you should first uninstall it from the host it is on. Then you may delete it from the Admin portal.

    Typically on Linux you will run:

    Typically on Windows you will run:

    a7022a60 image

    Manual Download

    Typically the installation is done from the Agilicus Admin portal. This will give you a link per platform. In rare cases you may wish to manually download, the linux are below for convenience. NOTE: you will need a ‘code’ from the admin web interface to install (under Resources/Connectors/New).


    More Information

    Below you will see cards for specific aspects of the connector (theory of operation, installation onto various platforms such as pfSense, Mikrotik, OpenWRT, Windows, etc.)

  • Moxa UC-8200 Zero-Trust Connector Install

    Moxa UC-8200 Zero-Trust Connector Install

    Moxa UC-8200

    Moxa UC-8200 Zero-Trust Connector Install

    Moxa UC-8200. Agilicus Connector.

    Overview

    The Moxa UC-8200 runs Debian 11 Linux. It is supported out-of-the-box by the Agilicus Connector, using the standard Linux install instructions.

    Once installed, you can remotely connect to the Moxa UC-8200, or, resources on adjacent networks through the Agilicus AnyX platform, regardless of network configuration or firewall settings.

    From the Agilicus Admin web interface, select Resources/Connectors/New. Give the connector a name, and then select the “Linux” tab, paste the resulting command line into a root shell and it will automatically setup and configure.

  • Agilicus Connector – Export Certificate

    Agilicus Connector – Export Certificate

    Windows Install

    Export Certificate

    Overview

    Applications generate a valid certificate. You can export this certificate for integration with other systems whenever it is issued or rotated. For example, VTScada requires a valid certificate for the server to be enabled with SSL.

    Requirements

    The connector associated with the application invokes a script when it learns about a new certificate.
      – The script must be accessible by the connector (e.g. on the same machine)
      – The script must be executable by the connector
      – You are responsible for ensuring the execution environment for the script

     For example, for the connector to execute a Python script, Python must be installed on the machine, and the machine must be configured to associate .py files with the Python interpreter. You are also responsible for installing any supporting packages used by your script.

    Windows Python Installation

    The Agilicus connector runs as a service. In order for the connector to invoke the Python script, Python must be installed on the local machine for all users. See https://docs.python.org/3/using/windows.html

    Once Python is installed, the connector will look for a script in the directory: C:\Program Files\agilicus\agent\plugins\certificate-exporter.py

    If there is no script found, no export will occur.

    Windows Example Script

    An example script is shown below, which will import the script as a .p12 file and store it into the Local Machine certificates storage.

    import sys
    import json
    import base64
    import tempfile
    import subprocess
    import os
    
    # load the certificate export json from stdin
    # see https://agilicus.com/www/api/certificate-export.schema.json
    cert_obj = json.loads(sys.stdin.readline())
    
    def import_certificate(obj):
        # create a temporary file. It must be closed
        # after write before calling certutil.
        tmp = tempfile.NamedTemporaryFile(delete=False)
        try:
            # retrieve the pkcs12 and base64 decode it
            pkcs12 = base64.b64decode(obj.get("pkcs12_b64"))
    
            # write the pkcs12 to the temporary file
            tmp.write(pkcs12)
            
            # close the file
            tmp.close()
    
            # now import the pkcs12 file into the local machine account
            subprocess.run(
                ["certutil",
                 "-f",
                 "-p",
                 obj.get("pkcs12_password"),
                 "-importpfx",
                 tmp.name,
                 ]
            )
        except Exception as exc:
            print(exc)
            raise exc
        finally:
            # after completion, delete the pkcs12 file
            os.unlink(tmp.name)
    
    import_certificate(cert_obj)

    Programming Interface Details

    The json document includes the PKCS #12-encoded certificate bundle and private key, as well as the pem-encoded certificate and private key, and various pieces of supporting data. To view the full details, consult the json definition for the json schema.

  • Sample: Synology Local SSL

    Sample: Synology Local SSL

    synology-nas-web

    Synology Local SSL

    The Agilicus connector can facilitate a publicly trusted local certificate for your Synology Web Interface.

    Overview

    100% of connections from the public networks into Agilicus AnyX are protected by Transport Level Security (TLS/SSL). Each endpoint has its own publicly-trusted certificate allocated, no wildcards, no fake certificates or certificate authority trusts to be injected. This is all done in a fully automatic fashion.

    In some cases, you wish to access the same resource from the local side, without going through Agilicus AnyX. Although we do not generally recommend this (it lowers the overall security since there is no strong authentication and multi-factor), it can be useful or required. In this sample, we show how to setup a Synology DS120 NAS web interface such that the local DNS resolves to its local IP, and, it is protected by the same public certificate that the Agilicus AnyX platform allocated. In this fashion a user on the local network can directly access the NAS without seeing broken ‘do you want to trust this site” messages.

    Setup

    Create Web Application

    First, configure the Synology web interface as a ‘Web Application’. We assign it a name (ds120), we select its via a connector we have previously installed on this NAS. We use ‘localhost’ and ‘port 5000’ for the upstream configuration (which is how we reach the web interface from inside the NAS). We then assign permission to our user.

    At this stage we should be able to navigate to the url, and reach the NAS. If you take your mobile phone, disconnect the WiFi, and then reach the url, it should work. If your local DNS overrides, you may still see the NAS directly with its TLS/SSL error, we will resolve that in the next section.

    fb3086e2 image
    a568960b image
    67062561 image
    cefae7a4 image
    057ac301 image
    22dcf92c image

    Export Certificate

    Referring to the instructions for exporting certificates, we see that the Connector will export the certificate if a Python script exists in a certain location (/opt/agilicus/agent/plugins/certificate-exporter.py).

    We can see where the Synology looks for its certificate:

    # ps -ef|grep nginx
    root      6609   654  0 17:22 pts/0    00:00:00 grep --color=auto nginx
    root      6872     1  0 Sep19 ?        00:00:00 nginx: master process /usr/bin/nginx -c /etc/nginx/nginx.conf.run -g pid /run/nginx.pid; daemon on; master_process on;
    http     31327  6872  0 Sep23 ?        00:01:24 nginx: worker process
    http     31328  6872  0 Sep23 ?        00:01:02 nginx: worker process
    # grep cert /etc/nginx/nginx.conf.run
        include /usr/syno/etc/www/certificate/system_default/cert.conf*;
    # ls -ld /usr/syno/etc/www/certificate/system_default/cert.conf*
    -rw------- 1 root root 224 Feb 20  2023 /usr/syno/etc/www/certificate/system_default/cert.conf
    # cat /usr/syno/etc/www/certificate/system_default/cert.conf
    ssl_certificate          /usr/syno/etc/www/certificate/system_default/73b8b5b1-7f63-4764-a54f-1a0d78d58dfd.pem;
    ssl_certificate_key      /usr/syno/etc/www/certificate/system_default/d27d6342-50fb-423f-b850-386b6a68e5ab.pem;
    

    OK, lets take a look at the ‘factory’ certificates:

    # openssl x509 -in /usr/syno/etc/www/certificate/system_default/73b8b5b1-7f63-4764-a54f-1a0d78d58dfd.pem -text
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 6280518885899342 (0x1650194132fc4e)
            Signature Algorithm: sha256WithRSAEncryption
            Issuer: C = TW, L = Taipel, O = Synology Inc., CN = Synology Inc. CA
            Validity
                Not Before: Feb 20 06:15:00 2023 GMT
                Not After : Feb 21 06:15:00 2024 GMT
            Subject: C = TW, L = Taipel, O = Synology Inc., CN = synology
            Subject Public Key Info:
                Public Key Algorithm: rsaEncryption
                    RSA Public-Key: (2048 bit)
                    Modulus:
                        00:df:33:80:97:f8:9d:88:a8:9f:49:35:7f:20:7a:
                        ba:68:26:47:3e:ed:7f:9f:79:3f:f3:6f:2c:31:1c:
                        38:36:cd:36:36:ed:bb:47:bf:29:cc:8c:e2:d2:3d:
                        16:4b:16:5b:16:7c:36:4e:c8:e8:05:f4:33:d6:7f:
                        91:7b:2c:c4:8b:3d:1e:18:19:d7:60:84:d4:08:db:
                        8e:b4:63:5e:bc:fa:e6:31:1f:5d:f8:64:27:76:4c:
                        a2:63:d4:a5:03:c7:cd:e9:83:f3:31:a7:29:c8:1d:
                        ed:bf:35:b5:02:c0:53:18:83:29:71:85:b2:15:b2:
                        0d:4e:11:0d:b1:4b:73:34:29:20:e4:5a:5c:f3:6d:
                        bf:9e:f7:85:f9:f6:8b:fd:63:26:66:d2:ac:0f:f5:
                        5b:e7:38:34:4d:e7:2d:db:ae:77:9f:69:0d:e6:3b:
                        3a:15:b1:28:ae:94:49:98:40:ed:d9:0f:2d:d6:bb:
                        f9:b3:64:33:7e:c0:6c:de:f0:eb:5d:f0:8d:3b:67:
                        60:01:69:b1:fa:b2:db:f3:33:88:a0:9c:e4:e9:f2:
                        3c:3a:eb:b5:b3:de:94:50:f3:3b:f0:70:a1:8d:f7:
                        e6:a6:c1:74:47:97:45:4d:b3:9a:27:f8:ad:44:db:
                        24:20:57:03:3f:01:e6:0b:82:dd:1f:49:ba:f7:cd:
                        e4:99
                    Exponent: 65537 (0x10001)
            X509v3 extensions:
                Netscape Comment:
                    mod_ssl generated custom server certificate
                Netscape Cert Type:
                    SSL Server
                X509v3 Key Usage: critical
                    Digital Signature, Key Encipherment
                X509v3 Extended Key Usage:
                    TLS Web Server Authentication, TLS Web Client Authentication
                X509v3 Subject Alternative Name:
                    DNS:synology
        Signature Algorithm: sha256WithRSAEncryption
             6d:38:84:e7:22:8f:f7:65:69:8a:98:8b:e7:fd:03:86:13:ce:
             ba:27:75:0a:c9:95:7c:38:07:6c:0c:7f:6f:2e:23:e8:68:52:
             cf:de:57:bd:d5:ee:75:1b:6e:f9:cf:58:74:36:f9:9a:3a:8c:
             4d:e0:7e:d7:21:00:ef:81:5e:4c:0c:59:34:cb:fe:37:60:0e:
             5a:81:f4:a6:fa:fb:39:82:1d:74:f7:6d:75:d4:72:e3:95:bc:
             a7:d3:76:df:e3:4f:d5:be:83:5a:3b:af:26:b8:1e:9f:d0:42:
             99:c3:6a:6a:36:13:a9:ef:bd:6f:88:42:71:d1:2f:ad:14:8d:
             5b:d9:17:b0:fc:bc:8b:f8:20:b2:26:25:c6:83:93:b7:2a:36:
             cc:85:f7:84:d3:01:13:40:a5:b9:ef:60:4e:47:46:26:84:b7:
             0e:da:eb:88:6c:75:9f:44:4c:0f:ab:f6:1b:0d:76:dc:4d:f1:
             04:87:11:e9:26:c4:12:cb:fe:ea:57:58:4b:85:1d:cc:de:c7:
             23:1d:55:1d:a1:d5:06:36:c6:4a:d0:15:e2:f0:34:9b:a2:05:
             2a:2c:b0:14:e1:a8:a4:95:99:17:df:3d:f7:f6:c3:ab:49:ff:
             b3:d9:ab:b2:50:51:cb:bb:aa:3c:72:e4:ba:a6:cf:4a:b1:4c:
             96:1d:1f:a6
    -----BEGIN CERTIFICATE-----
    MIIDsjCCApqgAwIBAgIHFlAZQTL8TjANBgkqhkiG9w0BAQsFADBRMQswCQYDVQQG
    EwJUVzEPMA0GA1UEBwwGVGFpcGVsMRYwFAYDVQQKDA1TeW5vbG9neSBJbmMuMRkw
    FwYDVQQDDBBTeW5vbG9neSBJbmMuIENBMB4XDTIzMDIyMDA2MTUwMFoXDTI0MDIy
    MTA2MTUwMFowSTELMAkGA1UEBhMCVFcxDzANBgNVBAcMBlRhaXBlbDEWMBQGA1UE
    CgwNU3lub2xvZ3kgSW5jLjERMA8GA1UEAwwIc3lub2xvZ3kwggEiMA0GCSqGSIb3
    DQEBAQUAA4IBDwAwggEKAoIBAQDfM4CX+J2IqJ9JNX8gerpoJkc+7X+feT/zbywx
    HDg2zTY27btHvynMjOLSPRZLFlsWfDZOyOgF9DPWf5F7LMSLPR4YGddghNQI2460
    Y168+uYxH134ZCd2TKJj1KUDx83pg/MxpynIHe2/NbUCwFMYgylxhbIVsg1OEQ2x
    S3M0KSDkWlzzbb+e94X59ov9YyZm0qwP9VvnODRN5y3brnefaQ3mOzoVsSiulEmY
    QO3ZDy3Wu/mzZDN+wGze8Otd8I07Z2ABabH6stvzM4ignOTp8jw667Wz3pRQ8zvw
    cKGN9+amwXRHl0VNs5on+K1E2yQgVwM/AeYLgt0fSbr3zeSZAgMBAAGjgZYwgZMw
    OgYJYIZIAYb4QgENBC0WK21vZF9zc2wgZ2VuZXJhdGVkIGN1c3RvbSBzZXJ2ZXIg
    Y2VydGlmaWNhdGUwEQYJYIZIAYb4QgEBBAQDAgZAMA4GA1UdDwEB/wQEAwIFoDAd
    BgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwEwYDVR0RBAwwCoIIc3lub2xv
    Z3kwDQYJKoZIhvcNAQELBQADggEBAG04hOcij/dlaYqYi+f9A4YTzrondQrJlXw4
    B2wMf28uI+hoUs/eV73V7nUbbvnPWHQ2+Zo6jE3gftchAO+BXkwMWTTL/jdgDlqB
    9Kb6+zmCHXT3bXXUcuOVvKfTdt/jT9W+g1o7rya4Hp/QQpnDamo2E6nvvW+IQnHR
    L60UjVvZF7D8vIv4ILImJcaDk7cqNsyF94TTARNApbnvYE5HRiaEtw7a64hsdZ9E
    TA+r9hsNdtxN8QSHEekmxBLL/upXWEuFHczexyMdVR2h1QY2xkrQFeLwNJuiBSos
    sBThqKSVmRffPff2w6tJ/7PZq7JQUcu7qjxy5Lqmz0qxTJYdH6Y=
    -----END CERTIFICATE-----

    OK, it is expecting a FQDN of ‘synology’, and, is self-signed. We don’t want this. lets overwrite it with our properly signed one. To do so, place a script called certificate-exporter.py in /opt/agilicus/agent/plugins (you may need to make this directory). The script might look as below (notice I hard-coded in my host name since this connector services more than one endpoint, and I only want to export one certificate).

    #!/bin/python
    
    import sys
    import json
    import base64
    import os
    
    # load the certificate export json from stdin
    # see https://agilicus.com/www/api/certificate-export.schema.json
    cert_obj = json.loads(sys.stdin.readline())
    
    def import_certificate(obj):
        if obj.get("common_name") == "ds120.dbt.agilicus.cloud":
            with open("/usr/syno/etc/www/certificate/system_default/cert.conf", "w") as fd:
                fd.write("ssl_certificate   /usr/syno/etc/www/certificate/nas.pem;\nssl_certificate_key /usr/syno/etc/www/certificate/nas.key;\n");
            with open("/usr/syno/etc/www/certificate/nas.pem", "w") as fd:
                fd.write(obj.get("certificate"))
            with open("/usr/syno/etc/www/certificate/nas.key", "w") as fd:
                fd.write(obj.get("key"))
    
            with open("/usr/syno/etc/certificate/_archive/DEFAULT", "r") as fd:
                def_cert_name = fd.read()
                def_cert_name = def_cert_name.strip()
            with open(f"/usr/syno/etc/certificate/_archive/{def_cert_name}/cert.pem", "w") as fd:
                fd.write(obj.get("certificate"))
            with open(f"/usr/syno/etc/certificate/_archive/{def_cert_name}/privkey.pem", "w") as fd:
                fd.write(obj.get("key"))
    
            os.system("/bin/systemctl reload nginx")
    
    import_certificate(cert_obj)

    Testing

    To test, we can remove the cached files (exported_certs.*) and then restart the connector

    -rwxr-xr-x 1 agilicus agilicus  844 Nov 13 18:29 certificate-exporter.py
    -rw------- 1 root     root     5788 Nov 13 18:38 exported_certs.json
    -rw------- 1 root     root        0 Nov 13 18:38 exported_certs.json.lock
    # rm exported_certs*
    # systemctl restart agilicus-agent

    We can test with curl and a DNS override:

    curl -v https://ds120.dbt.agilicus.cloud/ --resolve ds120.dbt.agilicus.cloud:443:172.16.0.109
  • Cisco IOx Zero Trust Connector Install

    Cisco IOx Zero Trust Connector Install

    Cisco IR1101 IOx

    Cisco IOx Zero Trust Connector Install

    Cisco IOx. Agilicus Connector.

    Overview

    The Cisco IOx family provides an excellent platform to run the Agilicus Connector. In this example we are working with the Cisco IR1101, suitable for rugged, embedded environments.

    The instructions below were tested on

    Cisco IR1101-K9
    17.11.1a

    Cisco IOx Zero Trust: Cisco Router Setup

    Follow the Cisco instructions on enabling IOx, enabling applications and routing. Some sample config is shown here, but this varies by platform. Key items required:

    1. Clock sync (ntp, GPS)
    2. Ability to reach https://www.agilicus.com/
    3. Ability to reach https://api.agilicus.com/

    Below we have achieved this with NAT but you can also use a bridge.

    interface VirtualPortGroup0
     ip address 192.168.100.1 255.255.255.0
     ip nat inside
    
    interface Vlan1
     ip address 192.168.2.2 255.255.255.0
     ip nat outside
    
    ntp server 0.pool.ntp.org
    
    ip dhcp pool vg0
     network 192.168.100.0 255.255.255.0
     default-router 192.168.100.1
     dns-server 1.1.1.1
    interface VirtualPortGroup0
     ip address 192.168.100.1 255.255.255.0
     ip nat inside
    
    interface Vlan1
     ip address 192.168.2.2 255.255.255.0
     ip nat outside
    
    ntp server 0.pool.ntp.org
    
    ip dhcp pool vg0
     network 192.168.100.0 255.255.255.0
     default-router 192.168.100.1
     dns-server 1.1.1.1
    
    ip name-server 1.1.1.1
    
    iox
    ip default-gateway 192.168.2.1
    
    ip access-list standard IOX_NAT
     10 permit 192.168.100.0 0.0.0.255
    
    ip nat inside source list IOX_NAT interface Vlan1 overload
    ip route 0.0.0.0 0.0.0.0 192.168.2.1

    Cisco IOx Zero Trust: Install

    On this platorm we will use a container-based install. This platform does not support standard container registries, so we will install the layers manually.

    First, download to your local computer the appropriate file for your platform (amd64 or arm64). The IR1101 in our example is arm64.

    5603e8e1 image

    Second, navigate to the IOx web admin, Configuration/Services/IOx.

    From here we will:

    1. Create Application
    2. Upload image (from above)
    3. Set Profile (ram/disk/cpu)
    4. Set networking
    5. Set environment variables (from Agilicus Admin)
    6. Set configuration volume
    7. Activate application
    8. Start application

    at which point the Agilicus connector will be running

    Cisco IOx Zero Trust: Detailed Steps

    Start Application

    Select the Agilicus Connnector and start it.

    (Optional) Diagnose Application

    You can examine the output logs, if needed, via ‘Manage’ and then ‘Log’ and ‘Download’

    (Optional) Diagnose Application Log

    You can examine the output logs, if needed, via ‘Manage’ and then ‘Log’ and ‘Download’

    Check Connector Status

    Within approximately 90 seconds you should see the Connector come online in the Agilicus admin UI.

    c08a1fb8 cisco ir1101 1

    Add New Application

    In the Cisco IOx web admin, select ‘Add New’ application.

    271adbcd cisco ir1101 2

    Upload Image

    Download to your local computer the appropriate file for your platform (amd64 or arm64). The IR1101 in our example is arm64.

    Upload this image to the IOx device.

    Name the Application ‘agilicus’.

    Activate

    Select ‘Activate’

    Copy Setup Configuration

    In the Agilicus Admin UI, create a connector. Install. use the ‘Docker’ instructions.

    Copy the 3 items shown in the image:

    -v agilicus:/etc/agilicus/agent
    -e AGILICUS_CHALLENGE_ID=…
    -e AGILICUS_CHALLENGE_CODE=…

    NOTE: the code times out after 10 minutes. If you copy this, and do not start the container within this time, you can generate a new one by closing and re-open the install dialog.

    Configure Application

    You may optionally configure the resource limits. The Agilicus Connector will typically consume < 256MiB memory, ~150MiB storage, and < 25% of 1 CPU.

    Configure the network to match your overall setup (bridge vs NAT).

    Uncheck ‘auto delete’, paste the command line from the previous step., Select Activate.

    At this stage you have successfully configured the Agilicus Connector on your Cisco IOx device. You may now configure individual services via the Agilicus admin interface.

    Sample things to consider would be SSH to the IOx device, the Web Admin of the IOx device, as well as other onwards resources.

    In our example router, the SSH management interface is 192.168.2.2. I added a SSH resource, named irr1101-ssh, with that as the IP. I was then able to sign in via Agilicus Profile and see the Router CLI.

  • Agilicus Connector – Snap

    Agilicus Connector – Snap

    snapcraft

    Agilicus Connector Snap

    The Agilicus Connector is packaged for Ubuntu Core20 on X86_64 and AARCH64.

    Overview: Agilicus Connector – Snap

    The Agilicus Connector is available as a multi-arch snap (X86_64 and AARCH64/ARM64). It is not currently published to Snapcraft, so it must be side-loaded.

    The installation steps are

    1. Download the snap .
    2. Create a Connector in the Agilicus Admin
    3. Set 2 snap parameters (code, id) as given from the Agilicus Admin

    At this stage the Agilicus Connector should be running and should stay up to date.

    Details

    Download the snap from the Agilicus website (https://www.agilicus.com/www/releases/secure-agent/stable/agilicus-connector_multi.snap). Install it with sudo snap install agilicus-connector_multi.snap --devmode --dangerous. This will make it unconstrained. NOTE: work is underway to restrict and publish.

    In the Agilicus Admin, use Resources/New to create your connector (or Resources/Overview to re-install if you are debugging and iterating). NOTE: if you do uninstall and re-install, remember to delete the stale instance.

    On the Install screen, use the ‘Manual’ instructions. You will copy the challenge-id parameter, and then run sudo snap set agilicus-connector setup.id=XXXXX of it. You will then copy the challenge-code, and run sudo snap set agilicus-connector setup.code=XXXX of it. See the below image.

    At this stage, the Agilicus connector should start automatically. You may see its logs as sudo snap logs -f agilicus-connector

    You should see your Connector transition to ‘Good’. You may also check the statistics on the action menu. A good first service to try is a ‘share’ since it will run entirely within the Snap. You might then try reaching a service on the host running the Agilicus Connector – Snap.

    Notes:

    1. Ensure that the time is synced via NTP on the device running the snap. The cryptography has a ‘not-before’ time that requires proper time sync.
    2. Ensure the device is able to reach www.agilicus.com (34.95.12.47), api.agilicus.com (35.203.36.11) on HTTPS port 443. You may test this with: curl https://www.agilicus.com/ and https://api.agilicus.com/v1/resolve/?name=www.agilicus.com.
    3. If you use your own domain, and run split-horizon DNS, ensure it properly resolves the CNAME.
  • Agilicus Connector – GL-MT3000 (Beryl AX)

    Agilicus Connector – GL-MT3000 (Beryl AX)

    GL-MT3000 (Beryl AX)

    Agilicus Connector – GL-MT3000 (Beryl AX)

    GL-MT3000 (Beryl AX) Background

    The GL-MT3000 (Beryl AX) has 1 x Gigabit Ethernet, 1 x 2.5 Gigabit Ethernet, 512MiB of RAM, and 256MiB of eMMC storage as well as WiFi 802.11AX. It is an excellent portable platform for demonstrations and field service to run the Agilicus Connector, supporting Cellular (via LTE), WiFI, Ethernet at a low cost point and small form factor.

    Installing Stock OpenWRT

    You may choose to run the Agilicus Connector on the GL-MT3000 (by using the advanced interface, and running the same commands as below to install ‘curl’, ‘ttyd’, and then the Agilicus Connector. Agilicus recommends replacing GL-iNet custom OpenWRT with the stock one, both for security, as well as compatibility and support.

    Connect your laptop to the ‘LAN’ port (or WiFi if you prefer). Sign in to the web interface at http://192.168.8.1/. Navigate to the ‘Advanced settings’, which will log you in to Luci. Download the stock firmware (https://openwrt.org/toh/gl.inet/gl-mt3000), specifically the ‘Firmware OpenWRT Upgrade’ target , and then install via the ‘Backup/Flash Firmware’.

    05f73aed image
    86cbe61a image
    0db73dda image

    At this stage you are running Stock OpenWRT with its enormous ecosystem of tools, and its very simple to use web interface. You may open http://192.168.1.1/ and do any initial setup.

    Agilicus Connector Install

    To install the Agilicus connector, first we install the pre-requisite curl. we will also install a web terminal (ttyd).

    67e1f708 image
    692e674c image
    552ecd8e image

    At this stage, we can install the Agilicus connector. From the Agilicus admin web interface, select ‘Resources/New/Connector’. Copy the Linux command line, paste it into the Services/Terminal on the GL-MT3000. It will complete automatically, no further configuration is needed.

    f1a95c65 image
    9a38186c image
    89c6d94d image

    (Optional) Sample Configuration: Connect to Local HTTP (OpenWRT LuCI)

    This walk through shows an example of how, once the connector is installed (as per above), configuration of an HTTP interface. Once these are configured you could use the firewall to disable all external access. The high level steps are:

    1. Create Web Resource (Agilicus Admin)
    2. Assign Web Resource Permission (Agilicus Admin)
    3. Open Web Interface to NanoPi (Agilicus Profile or direct)
    80554db0 image

    OK, let’s get started. This will take approximately 2 minutes.

    Create a new application. Give it a name (which must be valid as a hostname in format). You will later be accessing this as https://NAME.DOMAIN/. You might consider ‘gl-mt3000’ as a name.

    dc047beb image

    You may, if you wish, have a well-known alias to this new web interface. This is more commonly done with very public ones (e.g. a Wiki or Timesheet system). Leave it as default and the Agilicus AnyX will create the hostname for you.

    afafc5e5 image

    Select the connector from the previous step.

    f9075bc3 image

    The connector has to know where to send the request (it is a proxy). The ‘upstream’ in this case is the GL-MT3000 itself, e.g. localhost port 80.

    b1a2f5be image

    For a bit of additional security we can tie the ‘logout’ URL of the GL-MT3000 web interface to the Agilicus AnyX logout by copying in the URL of the logout. This is optional.

    We also suggest that named users with a single role, configured later, for this sample. Normally you would create a group, e.g. ‘Web Admins’ and assign users to it.

    At this stage we are done, select ‘Apply’.

    4bd7f6d0 image

    Now we will assign ourselves permission to use this new web resource.

    7de48b4f image

    To make the profile a bit more ‘fun’ we can now assign a logo (an icon) to the launch of this web interface. In this ‘define’ section we could also refine the Web Application Firewall rules etc.

    43727b23 image

    Any image file (we suggest about 512×512) is suitable for a logo.

    At this stage we are done. We have:

    1. created and installed a connector on this GL-MT3000
    2. created a Web resource (to the NanoPi itself)

    We can now test our work. Open https://profile.YOURDOMAIN/

    ccd9d640 image

    Once you have signed in, you will see an icon for the new web resource, if you click it, a new browser tab will open. Observe the URL (https://NAME.DOMAIN). You can use this directly without profile if you wish. If you sign in, you will see the GL-MT3000 web interface directly. Now try it from a different network (e.g. your mobile phone, disable WiFi). Observe you can still connect. Now try with an unprivileged user (e.g. a different Gmail account), observe you cannot sign in.

    The ‘profile’ interface acts as a launch pad for the end-user. It will act as a Progressive Web Application (e.g. ‘add to homescreen’ on your mobile), giving you a single launch icon.

    You may also use the resources it points to directly: it is your choice.

    50b7155e image
    d7026aad image

    We can test the SSH access. From profile, select the resource we created earlier.

    We will see a ‘login’ dialog appear, enter the username (root) and password to the GL-MT3000.

    At this stage, we should see an SSH terminal.

    From here, consider using the ‘Launcher’ install feature of profile, add the Browser Extension. You will now see an entry on your start menu for this SSH, opening the native client (e.g. if you have Putty or OpenSSH installed).

    Similarly to the Web Resource, only users with permission are able to sign in. You may also choose to enable multi-factor authentication on your user and observe how this functions with the Web..

  • Agilicus Connector High Availability

    Agilicus Connector High Availability

    Moxa UC-8200

    Agilicus Connector High Availability

    Multiple active-active connectors on multiple devices

    Overview

    The Agilicus Connector can be installed in a high-availability mode. In this mode, multiple copies of the connector will concurrently run. Each connector which is up and healthy will share in some of the network traffic. Encryption keys are shared across the connectors in such a way that they are still in the customer’s sole custody.

    NOTE

    The Agilicus Connector does not support High Availability if a Share is present. As a work-around, either create a Connector managing all resources other than Shares, or, use the Windows Cluster approach which does support a Share.

    The installation instructions for the first connector in a High Availability set are the same, and, for each subsequent one, similar.

    Installation

    Installation is simple.

    1. Create and install the first instance on a machine
    2. Install subsequent instances (up to 4) on other machines

    Pre-requisites:

    1. One connector must be up for a new one to be added
    2. All connectors must be able to reach the same network resources.

    Initial (First) Connector in High Availability Set

    The installation instructions for the first connector in a high availability set are the same as for non high-availability.

    d5613534 image
    0044ebe9 image
    dd20cb32 image

    At this stage, the first connector is installed. Ensure it transitions to “GOOD” since it must be up and running to join the other connectors to the cluster.

    Adding High Availability Peers (Subsequent Connectors)

    To add additional high-availability peers, simply use the ‘Actions/Install Connector’ option on the first instance we created above.

    7614dcb8 image
    04ec249b image

    At this stage we are done, and there are two connectors running in High Availability mode. Note the slight difference in the output of the installation at the end (“Joining existing cluster. This will fail if another connector in this cluster is not online“)

    INFO[2024-04-01T11:55:38-04:00] Starting connector - version v0.246.9
    INFO[2024-04-01T11:55:39-04:00] Check if the agilicus connector is already running as a service. If so stop it
    INFO[2024-04-01T11:55:39-04:00] Create file /usr/bin/agilicus-agent-wrapper.sh
    INFO[2024-04-01T11:55:39-04:00] Create file /etc/systemd/system/agilicus-agent.service
    INFO[2024-04-01T11:55:39-04:00] Will install to /agilicus-agent.service -> {/etc/systemd/system/agilicus-agent.service -r--r--r-- 0x14cf980}
    INFO[2024-04-01T11:55:39-04:00] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x <nil>}
    INFO[2024-04-01T11:55:39-04:00] Create a directory at /opt/agilicus/agent/tufmetadata/latest
    INFO[2024-04-01T11:55:39-04:00] Create a directory at /opt/agilicus/agent/tufmetadata/stable
    INFO[2024-04-01T11:55:40-04:00] Create a user and group named Agilicus to run the agilicus-agent service
    INFO[2024-04-01T11:55:40-04:00] Copy executable to /opt/agilicus/agent
    INFO[2024-04-01T11:55:40-04:00] Set permissions to Agilicus on /opt/agilicus/agent
    INFO[2024-04-01T11:55:40-04:00] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent
    INFO[2024-04-01T11:55:41-04:00] creating connector instance
    INFO[2024-04-01T11:55:41-04:00] Join a connector cluster
    INFO[2024-04-01T11:55:41-04:00] Joining existing cluster. This will fail if another connector in this cluster is not online
    INFO[2024-04-01T11:56:01-04:00] Start agilicus-agent service
  • Agilicus Connector Air Gap Machine With Containers

    Agilicus Connector Air Gap Machine With Containers

    person-setup-machine

    Agilicus Connector Air Gap Machine With Containers

    Create a nearly-fully airgapped machine, with interior containers, no way in, and only 1 way out via Agilicus Connector.

    Agilicus Connector Air Gap Machine With Containers

    Imagine we have a complex set of orchestrated containers. They interoperate with each other. But, we don’t want them reaching the Internet, or the Internet reaching them.

    Some or all of these containers have a need to use remote services. Perhaps a cloud provider, perhaps another set in another building.

    In this example we show how to:

    1. Block all inbound traffic to a Debian 12 host
    2. Block all outbound traffic except for Agilicus API + Dataplane
    3. Use a service forwarder to allow specific containers to reach specific remote services

    For the container runtime we will use docker. The example below is a Debian 12 host with all options default, with docker.io installed.

    Debian 12: Default Firewall Rules

    Before we start we can inspect the default firewall rules. In a nutshell these:

    1. allow all outbound traffic from the host to Internet
    2. allow all outbound traffic from containers to Internet
    3. allow all outbound traffic from containers to host

    Setup: Block inbound traffic, block outbound except to Agilicus Cloud, Local DNS/DHCP

    Note: you may wish to have console access rather than SSH access in case you make a mistake.

    We can see the Agilicus required IP/hostnames. For this example, we will allow (on port 443), these two IP:

    • 34.95.12.47 (www.agilicus.com)
    • 35.203.36.11 (api.agilicus.com)

    At this stage, we can test. First let us confirm that DNS works and that we can reach Agilicus WWW (for system updates):

    Now let us check that we cannot reach other websites:

    Now let us demonstrate that a docker container cannot escape:

    Not so fast, we have now blocked docker hub. For our scheme to work, we will need to either get all containers on the machine out of band, or allow a docker registry. I will demonstrate the out-of-band technique:

    OK, why did the container reach the Internet if the host cannot? For this we need to understand FORWARD (e..g routing) versus INPUT/OUTPUT. The Host is routing the docker traffic, we need some rules in the FORWARD path.

    At this stage, lets test again. We have made the default forward policy be to drop, and we have removed the MASQUERADE (NAT) rule.

    OK, we now have a set of containers which cannot reach the Internet on anything, and, a host that can reach a very limited set (DNS, DHCP, and Agilicus AnyX Cloud).

    Let us now check that the container can still reach the host. For this we will use two windows. In one, we will run ‘netcat’ to listen on a port, in the other we will test from the host to itself. In green, window 1, we run netcat in listen mode:

    $ nc -lvp 8888
    listening on [any] 8888 ...
    connect to [127.0.0.1] from localhost [127.0.0.1] 38276

    In black, we run netcat in connect mode, we observe it works.

    Let us now try from within the container

    Why did this hang? We are blocking all INPUT/OUTPUT except loopback (lo) and except for certain IP/port pairs. Let us add docker0 back in:

    OK at this stage we can test again, and it works. The container can reach the host (on all ports), but not the Internet.

    Install Agilicus Connector on Host

    Let us install the Agilicus connector.

    Why did this hang? As a shortcut in the command, it is using ‘agilicus.com’ and ‘http’. We can make a minor change:

    This now works, demonstrating that our above firewall rules prevent port 80 access.

    Next Steps

    You can save/restore your iptables rules with iptables-save and iptables-restore. You can install iptables-persistent package to make these load on reboot (or put the rules in e.g. /etc/rc.local).

    You may consider only allowing the containers to reach specific ports, where we would run the Agilicus connector.

    The final rule set we ended up with: