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.

Terms and Privacy Help Pricing About Blog Contact us Server Status Twitter