Configuration

Search…
Configuration
The configuration file used by ops (such as one passed as a parameter, e.g. ops --config myconfig.json) specifies various options and attributes of code execution, such as files to include, arguments, and environment variables. This file follows the standard json format.
For a complete sample of a configuration, see our sample.
Configuration Attributes
Args
Args is an array of arguments passed to your program to execute when running the image. Most programs will consider the program name as arg[0] but not all.
{
    "Args": ["ex.js"]
}
BaseVolumeSz
The BaseVolumeSz is an optional parameter you can pass to specify the size of the base volume. By default the size is the end of blocks written by TFS.
To specify 100 megabytes:
{
    "BaseVolumeSz": "100m"
}
To specify 1 gigabyte:
{
    "BaseVolumeSz": "1g"
}
Boot
TODO
BuildDir
TODO
CloudConfig
The CloudConfig configures various attributes about the cloud provider, we want to use with ops.
CWD #{cwd}
Some applications expect to have a working directory in a different place than where they have been placed. You can adjust this via the manifest variable 'cwd':
{
  "ManifestPassthrough": {
    "cwd": "/my_new/path"
  }
}
InstanceProfile
This configuration setting sets up an IAM role for an instance. Currently, this is only used for AWS but, in the future, it might be used to set roles for other cloud providers.
{
    "CloudConfig": {
        "InstanceProfile": "myrolename"
    }
}
BucketName
Bucket name is used to store Ops built image artifacts.
{
    "CloudConfig": {
        "BucketName": "my-bucket"
    }
}
DomainName
Updates DNS entry with the started instance IP.
{
    "CloudConfig": {
        "DomainName": "ops.city"
    }
}
EnableIPv6
This option is only supported on AWS.
If EnableIPv6 is set to true and a VPC is created, the new VPC will have ipv6 support. Otherwise, it doesn't affect the selected VPC ipv6 support.
{
    "CloudConfig": {
        "EnableIPv6": true
    }
}
Flavor
Specifies the machine type used to create an instance. Each cloud provider has different types descriptions.
{
    "CloudConfig": {
        "Flavor": "t2.micro"
    }
}
ImageName
Specifies the image name in the cloud provider.
{
    "CloudConfig": {
        "ImageName": "web-server"
    }
}
OPS_HOME
The OPS_HOME environment variable points to the location of where ops will store build images and releases locally. By default it is set to ~/.ops . However there are some use-cases where you might want it set to something else like so:
OPS_HOME=/opt/ops
Platform
Cloud provider we want to use with ops CLI.
Currently supported platforms:
Google Cloud Platform gcp
AWS aws
Vultr vultr
Vmware vsphere
Azure azure
Openstack openstack
Upcloud upcloud
Hyper-v hyper-v See further instructions about the cloud provider in dedicated documentation page.
{
    "CloudConfig": {
        "Platform": "gcp"
    }
}
ProjectID
Project ID is used in some cloud providers to identify a workspace.
{
    "CloudConfig": {
        "ProjectID": "proj-1000"
    }
}
SecurityGroup
Allows an instance to use an existing security group in the cloud provider.
On AWS, both the name and the id of the security group may be used as value.
{
    "CloudConfig": {
        "SecurityGroup": "sg-1000"
    }
}
Subnet
Allows an instance to use an existing subnet in the cloud provider.
On AWS, both the name and the id of the subnet may be used as value.
{
    "CloudConfig": {
        "Subnet": "sb-1000"
    }
}
Tags
A list of keys and values to provide more context about an instance or an image. There are a set of pre-defined tags to identify the resources created by ops.
{
    "CloudConfig": {
        "Tags": [
            {
                "key": "instance-owner",
                "value": "joe-smith"
            },
            {
                "key": "function",
                "value": "web-server"
            }
        ]
    }
}
Zone
Zone is used in some cloud providers to identify the location where cloud resources are stored.
{
    "CloudConfig": {
        "Zone": "us-west1-b"
    }
}
VPC
Allows instance to use an existing vpc in the cloud provider.
On AWS, both the name and the id of the vpc may be used as value.
{
    "CloudConfig": {
        "VPC": "vpc-1000"
    }
}
Debugflags
TODO
Dirs
An array of directory locations to include into the image:
{
    "Dirs": ["myapp/static"]
}
File layout on local host machine:
-myapp
    app
    -static
        -example.html
        -stylesheet
            -main.css
File layout on VM:
/myapp
    app
    /static
        -example.html
        /stylesheet
            -main.css
Env
A map of environment variables:
{
    "Env": {
        "Environment": "development",
        "NODE_DEBUG": "*"
    }
}
Exec Protection
Nanos has an 'exec protection' feature that prevents the kernel from executing any code outside the main executable and other 'trusted' files explicitly marked. The program is further limited from modifying the executable file and creating new ones. This flag may also be used on individual files within the children tuple. This prevents the application from exec-mapping anything that is not explicitly mapped as executable.
This is not on by default, however, as many JITs won't work with it turned on.
{
  "ManifestPassthrough": {
    "exec_protection": "t"
  }
}
Files
An array of file locations to include into the image:
{
    "Files": ["ex.js"]
}
Force
TODO
IdleOnExit
This option keeps a VM running after the user program exits successfully. The VCPUs remain halted.
{
    "IdleOnExit": true
}
Kernel
TODO
ManifestPassthrough
There is the concept of the manifest in Nanos where there exists many other config options that don't boil up to ops configuration, however, sometimes you still wish to pass these settings down to the manifest. Certain klibs, in particular, have variables that need to be set. To set them do this:
{
  "ManifestPassthrough": {
    "my_manifest_setting": "some_value"
  }
}
MapDirs
A map of a local directory to a different path on the guest VM. For example the below adds all files under /etc/ssl/certs on host to /usr/lib/ssl/certs on VM.
{
    "MapDirs": {"/etc/ssl/certs/*": "/usr/lib/ssl/certs" },
}
Mounts
TODO
NameServers
An array of DNS servers to use for DNS resolution. By default it is Google's 8.8.8.8.
{
    "NameServers": ["10.8.0.1"]
}
NightlyBuild
TODO
NoTrace
TODO
Program
TODO
ProgramPath
TODO
RebootOnExit
There is an option to reboot your application immediately if it crashes that is turned off by default, but you can enable it.
{
    "RebootOnExit": true
}
RunConfig
The RunConfig configures various attributes about the runtime of the ops instance, such as allocated memory and exposed ports.
Accel
Defines whether hardware acceleration should be enabled in qemu. This option is enabled by default.
{
    "RunConfig": {
        "Accel": true
    }
}
Bridged
Connects the unikernel network interface to a bridge with the name br0. The bridge name may be overriden with the property BridgeName.
{
    "RunConfig": {
        "Bridged": true
    }
}
BridgeName
Connects the unikernel network interface to a bridge with the name specified. If the bridge does not exist in host machine it is created.
{
    "RunConfig": {
        "BridgeName": "br1"
    }
}
CPUs
Specifies the number of CPU cores the unikernel is allowed to use.
{
    "RunConfig": {
        "CPUs": 2
    }
}
Debug
Opens a port in unikernel to allow a connection with the GDB debugger. See further instructions in Debugging. If debug is set to true the hardware acceleration (accel) is disabled.
{
    "RunConfig": {
        "Debug": true
    }
}
Gateway
Defines the default gateway IP of the network interface.
{
    "RunConfig": {
        "Gateway": "192.168.1.255"
    }
}
GdbPort
Define the gdb debugger port. It only takes effect if debug is enabled. By default the GdbPort is 1234.
{
    "RunConfig": {
        "GdbPort": 1234,
        "Debug": true
    }
}
Imagename
Sets the name of the image file.
{
    "RunConfig": {
        "Imagename": "web-server"
    }
}
InstanceName
Sets the name of the instance.
{
    "RunConfig": {
        "InstanceName": "web-server-instance"
    }
}
IPAddress
Defines the IP address of the network interface.
{
    "RunConfig": {
        "IPAddress": "192.168.1.75"
    }
}
The IP address has to be specified along with the netmask{#runconfig.netmask} and the gateway{#runconfig.gateway}, so the unikernel can assign the IP address to the network interface.
{
    "RunConfig": {
        "IPAddress": "192.168.1.75",
        "NetMask": "255.255.255.0",
        "Gateway": "192.168.1.1"
    }
}
IPv6Address
Defines the static IPv6 address of the network interface.
{
    "RunConfig": {
        "IPv6Address": "FE80::46F:65FF:FE9C:4861"
    }
}
Klibs
For example to run the NTP klib (eg: ntpd):
{
  "RunConfig":{
    "Klibs":["ntp"]
  }
}
Memory
Configures the amount of memory to allocated to qemu. Default is 128 MiB. Optionally, a suffix of "M" or "G" can be used to signify a value in megabytes or gigabytes respectively.
{
    "RunConfig": {
        "Memory": "2G"
    }
}
Mounts
Defines a list of directories paths in the host machine whose data will be copied to the unikernel.
{
    "RunConfig": {
        "Mounts": ["./files","./assets"]
    }
}
NetMask
Defines the netmask of the network interface.
{
    "RunConfig": {
        "NetMask": "255.255.255.0"
    }
}
Background
Starts unikernels in background. You can stop the unikernel using the onprem instances stop command.
{
    "RunConfig": {
        "Background": true
    }
}
Ports
A list of ports to expose. Alternatively, you can also use -p in the command line.
{
    "RunConfig": {
        "Ports": ["80", "8008"],
    }
}
ShowDebug
Enables printing more details about what ops is doing at the moment. Also, enables the printing of warnings and errors.
{
    "RunConfig": {
        "ShowDebug": true,
    }
}
ShowErrors
Enables printing errors with more details.
{
    "RunConfig": {
        "ShowErrors": true,
    }
}
ShowWarnings
Enables printing warnings details.
{
    "RunConfig": {
        "ShowWarnings": true,
    }
}
TapName
Connects the unikernel to a network interface with the name specified. If the tap does not exist in host machine it is created.
{
    "RunConfig": {
        "TapName": "tap0"
    }
}
UDPPorts
Opens ports that use UDP protocol.
{
    "RunConfig": {
        "UDPPorts": ["60", "70-80", "6006"],
    }
}
Verbose
Enables verbose logging for the runtime environment. As of now, it prints the command used to start qemu.
{
    "RunConfig": {
        "Verbose": true
    }
}
VolumeSizeInGb
This property is only used by cloud provider openstack and sets the instance volume size. Default size is 1 GB.
{
    "RunConfig": {
        "VolumeSizeInGb": 2
    }
}
TargetRoot
TODO
Version
TODO
Sample Configuration File
Below is a sample configuration file for a nodejs application.
{
	"Files": ["ex.js"],
	"Dirs": ["src"],
	"Args": ["ex.js "],
	"Env": {
		"NODE_DEBUG": "*",
		"NODE_DEBUG_NATIVE": "*"
	},
	"MapsDirs": {
		"src": "/myapp/code"
	},
	"Boot": "./staging/boot2.img",
	"Kernel": "./staging/stage4.img",
	"Mkfs": "./staging/mkfs",
	"DiskImage": "disk-image",
	"NameServers": ["10.8.0.1"],
	"RunConfig": {
		"Verbose": true,
		"Bridged": true,
		"Ports": [8008],
		"Memory": "2G"
	}
}
TargetConfig
There is currently limited support to adding cloud provider specific config. This is done as to not overload the other configuration settings.
Currently only the proxmox target has support here. For example:
{
  "TargetConfig": {
    "isoStorageName": "someothervalue"
  }
}
Basic Usage
Examples
Last modified 2d ago
Copy link
On this page
Configuration Attributes
Args
BaseVolumeSz
Boot
BuildDir
CloudConfig
CWD #{cwd}
Debugflags
Dirs
Env
Exec Protection
Files
Force
IdleOnExit
Kernel
ManifestPassthrough
MapDirs
Mounts
NameServers
NightlyBuild
NoTrace
Program
ProgramPath
RebootOnExit
RunConfig
TargetRoot
Version
Sample Configuration File
TargetConfig