Configure Opt-Server Commands
Introduction
After connecting your optimization server to PIFOP for the first time
— see Hosting an Optimization Server —
you are ready to configure the commands supported by your server.
You can support virtually any command line tool that
is installed in your machine — ampl,
gams,
python3,
g++,
etc. After configuring a command, you and
the Opt-server users will be able to call it from any PIFOP terminal.
See below how to add, modify or remove supported commands from your Opt-Server.
Add a command to the "commands" list
Your Opt-server looks at the configuration file config.json in its directory
to know what commands it supports. The configuration file is automatically created after you
connect your Opt-server to PIFOP for the first time.
All of the commands that you want to support have to go into the "commands" array of objects,
which you should add to the configuration file if it doesn't already exists.
Each entry in the "commands" array is an object that contains the configuration
of a supported command. The "commands" array and its entries look like this:
{
...
"commands" : [
{
"name" : "ampl",
"executable" : "/path/to/ampl"
...other properties...
}
]
}
In some cases, setting the properties "name" and "executable"
are sufficient. But others will require the explicity definition of other properties, such as
"mount-readable" and "environment-variables" for mounting and configuring
runtime dependencies. See below more about command properties.
Getting a command configuration to work may require some trial and error,
but this list of minimal configurations for common commands
should help you out.
After adding/modifying a command, you must restart the optimization server.
Command configuration
Aside from "name" and "executable",
each supported command can have a number of other properties.
The main purpose of these properties is to configure the sandbox that isolates the process, e.g.
which directories should be readable and which environment variables should be set.
See below a description of each command property.
Command Property
Description
"name"STRING
The name of the command is what you enter in a PIFOP terminal in order to call the command. It is
a good practice to give the command the same name of the executable that is invoked by it.
Example: "ampl"
"executable"STRING
Absolute path to the executable that is invoked by this command. Example: "/home/user/ampl-directory/ampl"
You can optionally set the mount destination where the executable's directory/file will be mounted. The mount destination of a given directory/file
is its path within the sandbox and it is set by using a colon : followed by the destination path.
Example: /path/outside:/path/inside
"auto-mount"STRING
Set the behaviour of the auto mount feature. This feature tries to mount all of the dynamic library directories/files
that are required to run the executable, aside from the executable's directory/file itself.
It can be one of the following:
-
"directories" — Default. Mount the directories where
the executable and dynamic libraries live.
-
"files" — Mount only the dynamic library and executable files.
-
"disabled" — Do not auto mount anything. If you disable this feature, you must
mannualy list all the files/directories required to run the executable using the "mount-readable"
property (see below).
This property is ignored if the "sandbox" property is set, in which
case the auto-mount feature will be "disabled"
"mount-readable"ARRAY OF STRINGS
List of directories/files that should be mounted into the sandbox that is created when this command is invoked and
readable by the process running the command. Use it, for instance, to mount dynamic library files necessary to run the executable. Example:
"mount-readable" : [
"/path/to/executable",
"/lib",
"/usr/lib"
]
You can optionally set the mount destination where the directory/file will be mounted. The mount destination of a given directory/file
is its path within the sandbox and it is set by using a colon : followed by the destination path.
Example: /path/outside:/path/inside
"mount-writable"ARRAY OF STRINGS
List of directories/files that should be mounted into the sandbox that is created when this command is invoked and
writable by the process running the command. Use it, for instance, to mount the /dev/null device. Example:
"mount-writable" : [
"/dev/null"
]
You can optionally set the mount destination where the directory/file will be mounted. The mount destination of a given directory/file
is its path within the sandbox and it is set by using a colon : followed by the destination path.
Example: /path/outside:/path/inside
"environment-variables"ARRAY OF STRINGS
List of environment variables that should be set and passed to the process running the command. Example:
"environment-variables" : [
"PATH=/bin:/usr/bin",
"LD_LIBRARY_PATH=/lib:/usr/lib"
]
Duplicate entries are concatenated into a colon-separated list, so the above example is equivalent to the following:
"environment-variables" : [
"PATH=/bin",
"PATH=/usr/bin",
"LD_LIBRARY_PATH=/lib",
"LD_LIBRARY_PATH=/usr/lib"
]
"inherit-user-id"BOOLEAN
If true, the user/group id of the user within the sandbox
will be the same as the user/group of the user running the opt-server.
Default: false
"enable-network"BOOLEAN
If true, the command sandbox will be granted internet access.
NOTE: Additionally to setting this property to true,
you will probably want to mount some internet configuration file(s), such as "/etc/resolv.conf"
for domain name resolution.
Default: false
"file-extensions"ARRAY OF STRINGS
List of file extensions associated with this command. This allows you to ommit the
command name when you enter a command line that starts with a file name ending with one of
the given extensions. Useful for configuring script interpreters, such as Python. For instance,
setting this property to [ "py" ] in a command that invokes
python3 makes the following commands equivalent:
> my-script.py --help
> python3 my-script.py --help
"prepend-options"STRING
String to be inserted just after the command name. For instance, if this property is set to "-R",
this command line entered on PIFOP: > ampl model.mod
is executed as if this was entered: > ampl -R model.mod
"append-options"STRING
Similar to "prepend-options", but sets a string to be appended to the command line.
For instance, if this property is set to "execMode=4",
this command line entered on PIFOP:
> gams model.gms
is executed as if this was entered: > gams model.gms execMode=4
"admin-only"BOOLEAN
If true, only users with admin rights will be able to invoke this command.
Default: false
"visible"BOOLEAN
Set this to false if you don't want to show users that this is a
supported command. For instance, the command will not appear on the help message
that is printed out when users enter help in a terminal. Default: true
Regardless of the value of this property, the command can still be called from the PIFOP IDE by any Opt-server user.
However, this property gives you the ability to keep
it a secret that the Opt-server supports a given command. This is useful if you want to
prevent regular users from calling a command that should only be called by users that know what they
are doing.
This should only be used as an obfuscation mechanism, not as a security measure.
Use the "admin-only" property if you want to actually prevent all
regular users from calling the command.
"sandbox"STRING
Use the settings of a named sandbox. This property allows you to easily use the same
sandbox configuration for multiple commands. See below how to setup and use a named sandbox.
When "sandbox" is set, the "auto-mount"
property is ignored and disabled.
Named "sandboxes"
Instead of explicitly setting the same sandbox properties for multiple commands, you can configure a
named sandbox and reuse it in the configuration of the commands.
In order to create a
named sandbox, add a "sandboxes" array to the config.json
if it doesn't exists. Each entry in this array is an object that represents a sandbox configuration
(see example below).
The properties of a sandbox are the same of a command, although not all command properties can be set
in a named sandbox configuration.
These are the properties that you can set in a named sandbox:
To use a named sandbox in a command configuration, set its "sandbox" property
to the name of the sandbox that you want to use. For instance, the following configuration file sets the
sandbox properties of "my-sandbox" and use that configuration on commands
"ampl" and "python3":
{
...
"sandboxes" : [
{
"name" : "my-sandbox",
"mount-readable" : [
"/path/to/dynamic-libaries",
"/path/to/ampl",
"/path/to/python3"
]
}
],
"commands" : [
{
"name" : "ampl",
"executable" : "/path/to/ampl",
"sandbox" : "my-sandbox"
},
{
"name" : "python3",
"executable" : "/path/to/python3",
"sandbox" : "my-sandbox"
}
]
}
Overwriting a named sandbox property
You can use a named sandbox configuration in a command
while also overwriting some of its properties. For instance, if you set the "mount-readable"
property in both the sandbox configuration and in the command configuration, the sandbox one is ignored
and the command configuration one is used.
The only exception to this rule is the "environment-variables" property, which,
instead of being overwritten, both arrays are concatenated and used as if they were a single array.