Configure 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. What tools and solvers do
you support? AMPL? GAMS? Python? You can support virtually any command line tool that
is installed in your machine. After configuring a supported command, you and
the opt-server users will be able to call it from a PIFOP terminal. See
below how to add, modify or remove supported commands from your Opt-Server.
Add a command to the "commands" list
Your optimization server looks at the configuration file config.json
to know what commands it supports. The configuration file is automatically created after you
connect your optimization server to PIFOP for the first time,
and is located in the same directory of the opt-server executable.
All of the supported commands have to go into the "commands" array of objects,
which you should add to the file if it doesn't already exists.
Each entry in the "commands" array is an object that contains the configuration
of a supported command that looks like this:
{
...
"commands" : [
{
"name" : "ampl",
"executable" : "/path/to/ampl"
...other 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 a "name", each supported command can have a number of other properties.
These properties affect mainly how the sandbox that isolates the process is configured, i.e., which directories should
be readable and which environment variables should be set, among other things. See below which properties can be
set and what do they do.
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
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
"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 of 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 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"
}
]
}
Overwrite 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 overwritten.
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.