- Set up a server
- Installing the Proxy
- Running the Proxy
- Cache, Store and Forward
- Cache Management
- Working with an Upstream Proxy
- Proxy Configuration
- Running as a service
- Creating proxy-enabled packages
- Getting help
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.
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.
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.
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
storemode 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.sqlitedatabase file to the FI instance location and rename it
frl-proxy.sqliteso 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.sqlitedatabase to Adobe servers and storing the responses in the same database.
- When the forwarding has completed, move the
frl-proxy.sqlite databasefrom the FI machine to the SI machine and rename it
- 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.sqlitefile. 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
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
storemode as a service.
- While the machines are connected to the network, an administrator runs the proxy in
cachemode 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.
- Set up a server to run FRL Online Proxy
- Install the proxy
- Acquire or generate SSL certificates if needed
- Run the proxy
- Set up logging if desired
- Run the proxy as a service
- Create and deploy proxy-enabled packages
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 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.
- Download the latest release.
- Open the application zip
- Copy the
frl-proxydirectory to your desired root location
- Open a PowerShell terminal
- Change directory to the frl-proxy location
> cd c:\path\to\frl-proxy
- Run the proxy
> .\frl-proxy.exe start
- Download the latest release. We recommend downloading it to the root of the proxy directory (e.g.
$ wget https://github.com/adobe/frl-online-proxy/releases/download/v0.5.1/frl-proxy-linux-0.5.1.tar.gz
- Extract the archive
$ tar xf frl-proxy-linux-0.5.1.tar.gz
- The archive will extract to the directory
frl-proxy, which contains the application binary
$ cd frl-proxy $ ./frl-proxy start
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
$ cd /path/to/frl-proxy
Start the proxy with the
# 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
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.
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
> .\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
-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
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
$ ./frl-proxy start -m cache
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] ssl = true [ssl] cert_path = "proxy-cert.pfx" cert_password = "password"
SSL mode can be toggled with the
--ssl command-line option:
$ ./frl-proxy start --ssl false
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
storemodes. 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
forwardmodes. When operating in
cachemode, 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] mode = "cache"
It can also be overridden using the
-m/--mode command-line option:
$ ./frl-proxy start --mode cache
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 command will clear the cache. No backup is made, so use this command with caution.
clear by itself will prompt for confirmation:
$ ./frl-proxy clear Really clear the cache? This operation cannot be undone. yes Cache has been cleared.
-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.
A proxy running in
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.
$ ./frl-proxy export proxy-store.sqlite Exported 24 stored request(s) to proxy-store.sqlite
A proxy running in
store mode can use the
import command to import all the stored responses that were received during a connected
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
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.
The configuration file is named
proxy-conf.toml by default. It uses TOML syntax.
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
[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 = ""
The configuration options in the
[proxy] section of the config file govern proxy behavior.
| ||Mode of operation - |
| ||The host IP the proxy listens on|
| ||The host port the proxy listens on in http (non-SSL) mode|
| ||The host port the proxy listens on in https (SSL) mode|
| ||Adobe Licensing Service endpoint|
| ||Enable ( |
The configuration options in the
[ssl] section of the config file specify SSL certificate options
| ||Path to SSL certificate file. Required if |
| ||SSL certificate password. IF not specified, then the environment variable |
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.
| ||Set the verbosity level for log output |
| ||Log to |
| ||Filename for file log output. Ignored if |
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.
| ||1||Errors that impact the performance or reliability of the application|
| ||2||Warnings that may indicate an issue, but should not impact general performance or reliability|
| ||3||Useful messages|
| ||4||Lower-priority messages that may be useful for debugging purposes|
| ||5||Low-level application debugging information|
[cache] specifies cache options
| ||Path to cache DB|
[network] configures upstream proxy options.
| ||Enable upstream proxy connection|
| ||Hostname or IP address of upstream proxy|
| ||Port to use for upstream proxy connection|
| ||Enable basic authentication?|
| ||Username for basic authentication|
| ||Password for basic authentication|
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 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.
> .\service.ps1 start Service "FRL Online Proxy" installed successfully! FRL Online Proxy: START: The operation completed successfully.
- Windows Powershell is required to run
- Administrator rights are required to install the service, so run
service.ps1from a Powershell Admin console.
service.ps1must be run from the
- A config file is required with the filename
proxy-conf.toml. This file must be in the same working directory as
service.ps1. See Proxy configuration for more information.
| ||Install and start the proxy as a service.|
| ||Stop the proxy service|
| ||Restart the proxy service|
| ||Stop the service if necessary and remove from the registry|
When the service is installed and running, you can view the status of the service in Windows Service Manager.
- Open the run dialog -
Windows Key + R
- Enter the command
- Press Enter
- The Service Manager will open showing a list of services installed on the system
- 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.
On Linux systems, the easiest way to set up a service for the proxy is systemd.
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.
- Download the latest release to the desired system.
- Extract the
frl-proxybinary to a system binary directory such as
- Generate a config file (see Proxy configuration)
- 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
- The log file should be written to a system log directory such as
- If you are going to run the proxy as a non-privileged user, change ownership of config file and log directory. Replace
[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
- Create the service configuration file
/etc/systemd/system/frl-proxy.serviceand open it in a text editor
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.
FRL-Online packages must be configured to use the proxy. Proxy settings are managed in the Adobe Admin Console.
- Log into the Admin Console
- Click the “Packages” tab on the top navigation bar.
- Click the blue “Create a Package” button.
- Select “Feature restricted licensing” and then “Next”
- Select “Online” and then “Next”
- Select entitlement, OS and product (app) options
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.
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.