Adobe FRL Online Proxy User Guide

Table of Contents

• Overview
  • Use Cases
    • Always-connected networks
    • Intermittently-connected networks
    • Fully-isolated networks
    • Isolated machines
  • Setup Overview
• Set up a server
• Installing the Proxy
  • Windows
  • Linux
• Running the Proxy
  • Command and usage summary
• SSL
• Cache, Store and Forward
• Cache Management
  • Clear
  • Export
  • Import
• Working with an Upstream Proxy
• Proxy Configuration
  • Proxy Options
  • SSL Options
  • Logging Options
  • Cache Options
  • Network Options
• Running as a service
  • Windows
  • Linux
• Creating proxy-enabled packages
• Getting help

Overview

The FRL Online Proxy is a simple solution for managing feature-restricted (FRL) Adobe licenses in an isolated network. It is a caching, terminating reverse proxy that facilitates license management for client machines that have restricted online access.

Each OS user of each Adobe application that activates via FRL Online must be able, when launching the application for the first time, to connect to Adobe’s licensing servers. If another OS user requires use of that same application (or if the original OS user wants to use a second application), then that other OS user (or that other application) must also, on their first launch, be able to connect to Adobe’s licensing servers.

This “first launch while connected” requirement presents a challenge for customers whose networks have limited or no access to the Internet. On such networks, it may be infeasible or even impossible for users to have network access to Adobe servers when launching their applications for the first time.

The FRL Online Proxy solves this customer problem by brokering requests to the licensing service on behalf of any client machine on the network. A customer who wishes to keep his users or their machines from contacting the internet can let them connect on their local network to the FRL Online Proxy, and then allow the FRL Online proxy to contact Adobe servers. This is completely safe for the customer, because the proxy will not accept anything but license requests from clients, and those requests will only be sent to the Adobe servers.

For customers who want to put their proxy on an internal network with is either intermittently connected or never connected to Adobe licensing servers, the proxy also supports license caching and store/forward relay capabilities. The license caching means that, if there are multiple users on a machine who use the same application, the proxy needs to connect to Adobe only for one of them, because the resulting activation will automatically be reused for other users on that machine. The store/forward capability means that, if a customer deploys the proxy on a fully isolated network, they can use an administrative process to collect the stored activation requests, send them to Adobe, and get the responses back to the internal proxy. That internal proxy will then use the cached responses to activate all the internal machines.

Use Cases

Always-connected networks

If a proxy instance can always contact Adobe servers, then it can be run in passthrough mode where it passes through every received request to Adobe and returns the response directly to the client. This setup is typically used for security purposes, because it prevents users on the proxy’s LAN from having direct internet access while still allowing their applications to be licensed via FRL Online. The advantage of not turning on caching in this case is that the proxy uses no database resources and thus can be run forever with no administrative overhead.

Intermittently-connected networks

If a proxy instance is on an intermittently-connected network, then it can be run in cache mode where it caches responses from Adobe while connected and then reuses them when offline. A proxy running in cache mode works similarly to one running in passthrough mode, but it always stores in the database the latest request it has received from each application on each machine, and whenever it receives a matching response to a request it stores that also. That way, after having run for a period of time connected, the proxy can successfully respond to all requests from machines on its local network, even if they come from OS users who have not previously activated their applications.

If new machines or applications are deployed to a network while the network is offline, the proxy will not be able to activate those machines or applications, but it will remember the requests for activation in its database. Then, when the proxy regains connectivity to Adobe, an administrator can perform one run of the proxy in forward mode, which will cause it to get responses to all of the cached requests. That way, when the proxy is taken back offline, the new machine or applications whose requests were forwarded and whose responses were stored will be able to activate as expected.

Because the proxy uses a file-based database when in cache mode, its machine must have enough disk space available to store one request/response pair for each application on each machine, where each pair is typically less than 10K bytes in size. In addition, as described above, proxies running in cache mode should be run once in forward mode whenever they have been offline while new machines or applications were deployed to their LAN.

Fully-isolated networks

If a proxy is going to be used effectively on a fully isolated network, then a second proxy on a connected network is required so that the two can run as a “store-forward pair”, as follows:

• Let’s call the two proxy instances SI and FI (for storing instance and forwarding instance). Configure SI and FI so they both use databases that are called proxy-db.sqlite. Make sure the FI instance has access to Adobe servers over the network.
• Run SI in store mode on a regular basis (using frl-proxy -m store). This will cause it to collect all requests that it cannot answer from its cache of responses, but because it’s on an isolated network it will not try to contact Adobe.
• From time to time, stop SI for a moment. Collect all the unanswered requests it has accumulated by invoking frl-proxy export stored-requests.sqlite. (This exports any unanswered requests in proxy-db.sqlite to a new database stored-requests.sqlite.) Then restart the SI instance as usual with frl-proxy -m store.
• Move the stored-requests.sqlite database file to the FI instance location and rename it frl-proxy.sqlite so it’s the database used by FI.
• Forward all the stored requests to Adobe by invoking FI with frl-proxy -m forward. This will complete quickly, sending all the stored requests in the frl-proxy.sqlite database to Adobe servers and storing the responses in the same database.
• When the forwarding has completed, move the frl-proxy.sqlite database from the FI machine to the SI machine and rename it forwarded-requests.sqlite.
• Stop the SI instance for a moment. Import the database of forwarded responses into the SI instance by invoking frl-proxy import forwarded-requests.sqlite. This will move all the received responses into the proxy-db.sqlite file. Restart the SI instance as usual with frl-proxy -m store.

At this point all the forward response will be available to the storing instance, so any apps whose requests had been stored will be successfully activated when they are next launched.

See cache management for more information on the proxy export and import commands.

Isolated machines

There is a variant of the store-forward architecture described above that can be used to pre-activate all the applications on an isolated machine. In this use case, we have one or more machines that are being set up for use on an isolated network, but during the setup process they have access to the network. In this case, the procedure is as follows:

• In addition to installing the applications and (proxy) licenses on the isolated machines, each isolated machine also gets configured with its own instance of the FRL Proxy (using a trusted certificate for localhost) that is configured to run in store mode as a service.
• While the machines are connected to the network, an administrator runs the proxy in cache mode and launches each of the applications that are to be activated.
• Then the machines are put in their isolated locations.

Because activating the applications in cache mode will cache the initial activation responses in the database, each machine’s proxy (now running in store mode) will be able to activate the application even when they are launched for the first time by other OS users on the isolated machines.

Setup Overview

1. Set up a server to run FRL Online Proxy
2. Install the proxy
3. Acquire or generate SSL certificates if needed
4. Run the proxy
5. Set up logging if desired
6. Run the proxy as a service
7. Create and deploy proxy-enabled packages

Set up a server

FRL Online Proxy will run on any modern Windows or Linux server. To run in passthrough mode, the server must be part of the isolated network and be able to communicate with Adobe’s licensing service (https://lcs-cops.adobe.io). It does not require Internet access to any other host or service.

If the server does not have consistent (or any) access to the licensing service, the proxy should be run in cache or store mode. cache mode will cache all license activation and deactivation requests from FRL clients and attempt to fulfill them with the licensing service. store will just cache requests without attempting to contact the licensing service.

We recommend creating a dedicated user account to run the proxy service. Note that it may be necessary to elevate this account’s privileges if the proxy needs to listen on privileged ports like 80 or 443.

Regardless of the port that will be used, the system must be configured to allow traffic from any host on the desired port (e.g. 0.0.0.0:8443).

Installing the Proxy

Windows

1. Download the latest release.
2. Open the application zip
3. Copy the frl-proxy directory to your desired root location
4. Open a PowerShell terminal
5. Change directory to the frl-proxy location

   > cd c:\path\to\frl-proxy
   

6. Run the proxy

   > .\frl-proxy.exe start
   

Linux

1. Download the latest release. We recommend downloading it to the root of the proxy directory (e.g. /home/[user])

   $ wget https://github.com/adobe/frl-online-proxy/releases/download/v0.5.1/frl-proxy-linux-0.5.1.tar.gz
   

2. Extract the archive

   $ tar xf frl-proxy-linux-0.5.1.tar.gz
   

3. The archive will extract to the directory frl-proxy, which contains the application binary

   $ cd frl-proxy
   $ ./frl-proxy start
   

Running the Proxy

The proxy service and associated tools are designed to be used from the command-line.

Open a command-line terminal on the server and switch to the frl-proxy directory.

$ cd /path/to/frl-proxy

Start the proxy with the start command.

# Windows
> .\frl-proxy.exe start

# Linux
$ ./frl-proxy start

When you start the proxy for the first time, you will be prompted to specify a few configuration options. This includes run mode, host IP, host ports, SSL info, caching info, etc. These settings are saved to a configuration file. When the configuration file is present, the proxy will start without prompting for these options an additional time.

Example configuration transcript:

Creating initial configuration file...
The proxy has four modes: cache, store, forward, and passthrough.
Read the user guide to understand which is right for each situation.
Proxy mode: cache
The proxy uses a SQLite database to keep track of requests and responses.
The proxy will create this database if one does not already exist.
Name of (or path to) your database file: proxy-cache.sqlite
The host and port of the proxy must match the one in your license package.
Host IP to listen on: 0.0.0.0
Host port for http (non-ssl) mode: 8080
Your proxy server must contact one of two Adobe licensing servers.
Use the variable IP server unless your firewall doesn't permit it.
Adobe licensing server: Variable IP server (lcs-cops.adobe.io)
MacOS applications can only connect to the proxy via SSL.
Windows applications can use SSL, but they don't require it.
Use SSL? yes
Host port for https mode: 8443
The proxy requires a certificate store in PKCS format to use SSL.
Read the user guide to learn how to obtain and prepare this file.
Name of (or path to) your cert file: proxy-cert.pfx
Usually, for security, PKCS files are encrypted with a password.
Your proxy will require that password in order to function properly.
You have the choice of storing your password in your config file or
in the value of an environment variable (FRL_PROXY_SSL.CERT_PASSWORD).
Do you want to store a password in your configuration file? no
Do you want to customize your proxy server's logging configuration? yes
The proxy can log to the console (standard output) or to a file on disk.
Log destination: console
The proxy will log errors, warnings and summary information.
Do you want to adjust the level of logged information? yes
Read the user guide to find out more about logging levels.
Log level: debug
Wrote config file 'proxy-conf.toml'

Once the configuration wizard completes, configuration options are written to proxy-conf.toml.

Once the configuration file is created, run the same command to start the proxy.

# Windows
> .\frl-proxy.exe start

# Linux
$ ./frl-proxy start

The configuration file can be edited in any text editor. You can also use the configure command to initiate a walkthrough of configuration options similar to the one presented on initial configuration.

Command and usage summary

Proxy functionality is driven by command. The main command, start, is used to run the proxy according to the configuration file.

Other commands exist to help configure the proxy or manage the cache. To get a full list of supported options and commands, pass the -h or --help option.

> .\frl-proxy.exe -h

frl-proxy 1.0.0
FRL Proxy

USAGE:
    frl-proxy.exe [FLAGS] [OPTIONS] <SUBCOMMAND>

FLAGS:
    -d               Specify once to force log level to debug. Specify twice to force log level to trace
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -c, --config-file <config-file>    Path to config file [default: proxy-conf.toml]
    -l, --log-to <log-to>              Override configured log destination: 'console' or 'file'. You can use just the
                                       first letter, so '-l c' and '-l f' work

SUBCOMMANDS:
    clear        Clear the cache (requires confirmation)
    configure    Interactively create the config file
    export       Export stored requests for a forwarder
    help         Prints this message or the help of the given subcommand(s)
    import       Import stored responses from a forwarder
    start        Start the proxy server

This not only documents supported commands, but shows which flags and options can be used with any command.

• -c/--config-file - specify config file path (default is proxy-conf.toml)
• -d - change log verbosity
• -l/--log-to - change log target

Any of these options must be specified before the command. For example:

$ ./frl-proxy -l console -c /path/to/proxy-conf.toml start

The start command provides a limited number of command-line options to override certain configuration file options.

    -m, --mode <mode>    Mode to run the proxy in, one of passthrough, cache, store, or forward. You can use any prefix
                         of these names (minimally p, c, s, or f)
        --ssl <ssl>      Enable SSL? (true or false)

These are specified after the start command.

$ ./frl-proxy start -m cache

SSL

The proxy supports both SSL (https) and non-SSL (http) clients. This allows customers the opportunity to examine the actual data transferred during the activation process and so ensure that no sensitive data is being exchanged. (Please note: Adobe applications running on MacOS cannot be configured to send activation requests via HTTP, but customers can use an HTTPS to HTTP proxy between those applications and the FRL proxy so that it can be used in non-SSL-client mode.)

SSL mode requires an X.509 SSL certificate and password. The certificate file should be secured with limited file permissions so that only the account running the proxy can read it.

The password can be stored in plain text in the configuration file or in the environment variable FRL_PROXY_SSL.CERT_PASSWORD. If you store your password in the configuration, be sure to limit access to that file.

The SSL certificate must be trusted by the client machines that contact the proxy, but it need not be a publicly-signed certificate (that is, it can be a self-signed certificate that is installed on the client machines and marked as trusted). For testing, you may wish to use a free, short-lived, renewable, publicly-signed certificate obtained from Let’s Encrypt. Consult your organization’s network security team if you need to use a long-lived, publicly-signed certificate.

SSL options are configured in proxy-conf.toml:

[proxy]
ssl = true

[ssl]
cert_path = "proxy-cert.pfx"
cert_password = "password"

SSL mode can be toggled with the --ssl command-line option:

Example:

$ ./frl-proxy start --ssl false

Cache, Store and Forward

The most basic mode, passthrough, forwards live calls to Adobe’s licensing services without caching any data. It doesn’t cache any license activation or deactivation requests or responses, and requires a live connection to the Internet at all times.

The proxy can be set up to use a local cache to store data for various use cases.

• Requests - Activation and deactivation requests are cached in cache and store modes. If an activation/deactivation response for a given request is unavailable, the proxy stores the request for later forwarding (when it has internet access).
• Responses - Activation and deactivation responses are cached in cache and forward modes. When operating in cache mode, if a request comes in whose matching response is already in the cache, the proxy will return that response even if it cannot contact Adobe servers.

The mode can be set in proxy-conf.toml:

[proxy]
mode = "cache"

It can also be overridden using the -m/--mode command-line option:

$ ./frl-proxy start --mode cache

Cache Management

The proxy provides commands to clear, import or export the cache.

    clear        Clear the cache (requires confirmation)
    export       Export stored requests for a forwarder
    import       Import stored responses from a forwarder

Clear

The clear command will clear the cache. No backup is made, so use this command with caution.

Running clear by itself will prompt for confirmation:

$ ./frl-proxy clear
Really clear the cache? This operation cannot be undone. yes
Cache has been cleared.

The -y option can be used to bypass this confirmation, in case you need to clear the cache automatically without human interaction:

$ ./frl-proxy clear -y
Cache has been cleared.

Export

A proxy running in cache or store mode can use the export command to export all unfulfilled license requests to a database file.

frl-proxy.exe-export 1.0.0
Export stored requests for a forwarder

USAGE:
    frl-proxy.exe export <export-path>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <export-path>

export takes one positional argument - the filename of the database file that will contain exported data.

Example:

$ ./frl-proxy export proxy-store.sqlite
Exported 24 stored request(s) to proxy-store.sqlite

Import

A proxy running in cache or store mode can use the import command to import all the stored responses that were received during a connected cache or forward session.

frl-proxy.exe-import 1.0.0
Import stored responses from a forwarder

USAGE:
    frl-proxy.exe import <import-path>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <import-path>

The positional argument specifies that path of a data file to import.

$ ./frl-proxy import proxy-store.sqlite
Imported 24 forwarded request/response pair(s) from proxy-store.sqlite

Working with an Upstream Proxy

The FRL Online Proxy can be configured to use an upstream proxy in order to communicate with Adobe’s licensing service. It can be used with no authentication or with basic authentication. It can be configured using the interactive configuration wizard (with ./frl-proxy configure) or manually in the config file.

Proxy Configuration

The configuration file is named proxy-conf.toml by default. It uses TOML syntax.

Running start for the first time will start a configuration wizard that will prompt you to set up the configuration file. The configuration file can be updated at any time by using the configure command.

Example:

[proxy]
mode = "cache"
host = "0.0.0.0"
port = "8080"
ssl_port = "8443"
remote_host = "https://lcs-cops.adobe.io"
ssl = true

[ssl]
cert_path = "proxy-cert.pfx"
cert_password = ""

[logging]
level = "debug"
destination = "console"
file_path = "proxy-log.log"

[cache]
db_path = "proxy-cache.sqlite"

[network]
use_proxy = false
proxy_host = "127.0.0.1"
proxy_port = "8888"
use_basic_auth = false
proxy_username = ""
proxy_password = ""

Proxy Options

The configuration options in the [proxy] section of the config file govern proxy behavior.

SSL Options

The configuration options in the [ssl] section of the config file specify SSL certificate options

Logging Options

Options in the [logging] section govern logging behavior. By default, the proxy will log to the console (stdout) at the info verbosity level. The config can be used to change the console logging verbosity level or write log data to a file at a potentially different verbosity level.

Verbosity settings

The log verbosity level governs the nature and amount of information that is written to the log. The proxy supports five levels, which can be set in the config file. Log messages are prioritized based on message type - setting verbosity to a certain level will write messages at that level’s priority and anything above it. For example, setting the level to warn will output warnings and errors.

Cache Options

[cache] specifies cache options

Network Options

[network] configures upstream proxy options.

Running as a service

To ensure the highest level of availability and reliability, the proxy should be run as a service. This ensures that the proxy is always running. If the service is interrupted for any reason (such as system reboot), it will automatically restart.

There are different methods for installing and enabling the proxy as a service depending on the environment.

Windows

Windows realeases of FRL Online Proxy include tools for setting up the service. The script bin\service.ps1 provides a simple interface for managing the proxy as a service.

Example:

> .\service.ps1 start
Service "FRL Online Proxy" installed successfully!
FRL Online Proxy: START: The operation completed successfully.

Notes:

• Windows Powershell is required to run service.ps1
• Administrator rights are required to install the service, so run service.ps1 from a Powershell Admin console.
• service.ps1 must be run from the frl-proxy working directory
• A config file is required with the filename proxy-conf.toml. This file must be in the same working directory as frl-proxy.exe and service.ps1. See Proxy configuration for more information.

Commands:

When the service is installed and running, you can view the status of the service in Windows Service Manager.

1. Open the run dialog - Windows Key + R
2. Enter the command services.msc
3. Press Enter
4. The Service Manager will open showing a list of services installed on the system
5. Ensure that FRL Online Proxy is installed, running and has a Startup Type of “Automatic”

If something doesn’t work as expected, see Getting help.

Linux

On Linux systems, the easiest way to set up a service for the proxy is systemd.

Note: sudo privileges are required for many of these steps. We recommend creating or designating a non-privileged user account that will run the proxy and own the configuration and log files.

1. Download the latest release to the desired system.
2. Extract the frl-proxy binary to a system binary directory such as /usr/bin
3. Generate a config file (see Proxy configuration)
4. Open the config file in a text editor and configure proxy and logging settings (host, ssl settings)
   • If the proxy will be run by a non-privileged account, it is necessary to set the proxy to listen on a port number higher than 1024 (e.g. 4343)
   • The config file should be copied to a system data directory (we recommend /etc/frl-proxy)
   • The log file should be written to a system log directory such as /var/log (we recommend /var/log/frl-proxy)
5. If you are going to run the proxy as a non-privileged user, change ownership of config file and log directory. Replace [user] and [group] with the user and group of the non-privileged account.
   • sudo chown [user]:[group] /etc/frl-proxy/proxy-conf.toml
   • sudo chown -R [user]:[group] /var/log/frl-proxy
6. Create the service configuration file /etc/systemd/system/frl-proxy.service and open it in a text editor

7. Copy this example configuration to the editor. Be sure to change the paths to the proxy binary and config file if necessary. And replace [user] with the name of the account that will run the proxy.

   [Unit]
   Description=FRL Online Proxy
   After=network.target
   StartLimitIntervalSec=0
   
   [Service]
   Type=simple
   Restart=always
   RestartSec=1
   User=[user]
   ExecStart=/usr/bin/frl-proxy -c /etc/frl-proxy/proxy-conf.toml start
   
   [Install]
   WantedBy=multi-user.target
   

With the service config in place, the service can be controlled with systemctl. Here are some examples of how to manage the service.

# Enable/disable determines if the service will start on boot
sudo systemctl enable frl-proxy
sudo systemctl disable frl-proxy

# Start/stop will manually start and stop the service, restart will stop and then start it
sudo systemctl start frl-proxy
sudo systemctl stop frl-proxy
sudo systemctl restart frl-proxy

# If any changes are made to the frl-proxy.service config, the systemd daemon must be reloaded
sudo systemctl daemon-reload

If something doesn’t work as expected, see Getting help.

Creating proxy-enabled packages

FRL-Online packages must be configured to use the proxy. Proxy settings are managed in the Adobe Admin Console.

1. Log into the Admin Console
2. Click the “Packages” tab on the top navigation bar.
3. Click the blue “Create a Package” button.
4. Select “Feature restricted licensing” and then “Next”
5. Select “Online” and then “Next”
6. Select entitlement, OS and product (app) options

7. On the next page, under “Management Options”, select “Contact Adobe through a reverse proxy”

   

   Update the “DNS Entry or IP address” field to point to the FRL Online Proxy service. This can be a plain IP address or a hostname. Don’t forget to specify the port number if using a non-standard port.

Getting help

All bug requests, feature requests, questions and feedback submissions are handled with Github issues. Please create a new issue if you need any assisance or support.