cordctl is a command-line tool for interacting with XOS. XOS is part of the SEBA NEM and part of CORD, so by extension this tool is useful for interacting with SEBA and CORD deployments. cordctl makes use of gRPC to connect to XOS and may by used for administration of a remote pod, assuming the appropriate firewall rules are configured. Typically XOS exposes its gRPC API on port 30011.
Binaries for cordctl are published at https://github.com/opencord/cordctl/releases and may be directly downloaded and used on Linux, MAC, or Windows platforms.
Additionally, the source for cordctl is available at https://github.com/opencord/cordctl and may be downloaded and built. cordctl is written in golang, and go version 1.12 or above must be installed in order to build from source.
If you would like to contribute to cordctl, the preferred process is to submit patches for code review through gerrit at https://gerrit.opencord.org.
Typically a configuration file should be placed at ~/.cord/config as cordctl will automatically look in that location. Alternatively, the -c command-line option may be used to specify a different config file location. Below is a sample config file:
server: 10.201.101.33:30011 username: admin@opencord.org password: letmein grpc: timeout: 10s
The server, username, and password parameters are essential to configure access to the XOS container running on your pod.
To generate a config file on stdout from the currently configured settings, the command cordctl config may be used.
The -h option can be used at multiple levels to get help, for example:
# Show help for global options cordctl -h # Show help for model-related commands cordctl model -h # Show help for the model list command cordctl model list -h
cordctl supports shell completion for the bash shell. To enable shell Completion you can use the following command on most *nix based system.
source <(cordctl completion bash)
If this does not work on your system, as is the case with the standard bash shell on MacOS, then you can try the following command:
source /dev/stdin <<<"$(cordctl completion bash)"
If you which to make bash shell completion automatic when you login to your account you can append the output of cordctl completion bash to your $HOME/.bashrc:
cordctl completion bash >> $HOME/.bashrc
cordctl has several commands for interacting with models in XOS:
cordctl modeltype list ... list the types of models that XOS supports.cordctl model list <modelName> ... list instances of the given model, with optional filtering.cordctl model update <modelName> <id> --set-json <json> ... update models with new fields.cordctl model delete <modelName> <id> ... delete models.cordctl model create <modelName> --set-json <json> ... create a new model.cordctl model sync <modelName> <id> ... wait for a model to be synchronized.cordctl model setdirty <modelName> <id> ... set a model dirty so it will be synchronized.XOS supports a dynamic set of models that may be extended by services that are loaded into XOS. As such the set of models that XOS supports is not necessarily fixed at initial deployment time, but may evolve over the life cycle of an XOS deployment as services are added, removed, or upgraded. The modeltype list command allows you to query the set of model types that XOS supports. For example,
# Query available model types cordctl modeltype list
The basic syntax for listing models (cordctl model list <modelName>) will list all objects of a particular model. Filtering options can be added by using the --filter argument and providing a comma-separated list of filters. If the filters contain characters that the shell would interpret, such as spaces or >, < or ! then you'll need to escape your filter specifier. For example,
# List slices that have id > 10 and controller_kind = Deployment cordctl model list Slice --filter "id>10, controller_kind=Deployment"
Supported operators in the filters include =, !=, >, <, >=, <=, ~=, and [=.
The core also permits models to be filtered based on state, and the --state argument can be used to filter based on a state. States include all, dirty, deleted, dirtypol, and deletedpol. default is a synonym for all. For example,
# List deleted ONOSApps cordctl model list ONOSApp --state deleted
The ~= operator is a regular expression search, and the [= operator is a substring search. For example,
# List slices that match the regular expression .*-operator ./cordctl model list Slice --filter "name~=.*-operator" # List slices that contain the substring etcd ./cordctl model list Slice --filter name[=etcd
The model update command is a flexible way to update one or more models. The most basic syntax uses one or more model IDs. For example,
# Update Site 1 and set its site_url to http://www.opencord.org/ cordctl model update Site 1 --set-field site_url=http://www.opencord.org/
Alternatively you may specify a JSON-formatted dictionary. Make sure to properly quote your JSON dictionary when using it as a command line argument. For example,
# Update Site 1 and set its site_url to http://www.opencord.org/ cordctl model update Site 1 --set-json '{"site_url": "http://www.opencord.org/"}'
If you don't know the ID of the object you wish to operate, or if you want to update several objects at the same time that have something in common, then you can use a --filter argument instead of an ID. For example,
# Update all sites named "mysite" and set its site_url to http://www.opencord.org/ cordctl model update Site --filter name=mysite --set-field site_url=http://www.opencord.org/
The syntax for deleting models is similar to that for updating models. You may delete by specifying one of more IDs, or you may delete by using a filter. For example,
# Delete Slice 1 cordctl model delete Slice 1 # Delete the Slice named myslice cordctl model delete Slice --filter name=mylice
The model create command allows you to create new instances of a model in XOS. To do this, specify the type of the model that you want to create and the set of fields that populate it. The set of fields can be set using a name=value syntax or by passing a JSON object. The following two examples are equivalent,
# Create a Site by using set-field cordctl model create Site --set-field name=somesite,abbreviated_name=somesite,login_base=somesite # Create a Site by passing a json object cordctl model create Site --set-json '{"name": "somesite", "abbreviated_name": "somesite", "login_base": "somesite"}'
All XOS operations are by nature asynchronous. When a model instance is created or updated, a synchronizer will typically run at a later time, enacting that model by applying its changes to some external component. After this is complete, the synchronizer updates the timestamps and other metadata to convey that the synchronization is complete.
Asynchronous operations are often inconvenient for test infrastructure, automation scripts, and even human operators. cordctl offers some features for synchronous behavior.
The first is the model sync command that can sync models based on ID or based on a filter. For example,
# Sync based on ID cordctl model sync ONOSApp 17 # Sync based on a field filter cordctl model sync ONOSApp --filter name=olt
The second way to sync an object is to use the --sync command when doing a model create or a model update. For example,
cordctl model create ONOSApp --sync --set-field name=myapp,app_id=org.opencord.myapp
XOS determines when a model is dirty by comparing timestamps. Each model has an updated timestamp that indicates the last time the model was updated. If this timestamp is newer than the enacted or policed timestamps then sync steps or policies will be run respectively. There is no direct way to modify the updated timestamp via the API since timestamps are managed by the XOS core. cordctl provides the setdirty command to cause models to be dirtied without altering the other fields of the model. When setdirty is used, the updated timestamp will be set to the current time. The setdirty command may be used with either an ID or a filter or the --all flag.
# Set model dirty based on ID cordctl model setdirty ONOSApp 17 # Set model dirty based on a field filter cordctl model setdirty ONOSApp --filter name=olt # Set all ONOSApp models dirty cordctl model setdirty ONOSApp --all
If you wish to query which models are dirty (for example, to verify that a previous setdirty worked as expected) then the --state dirty argument may be applied to the model list command. For example,
# Get a list of dirty ONOS Apps cordctl model list ONOSApp --state dirty
Note: Not all models have syncsteps or policies implemented for them. Some models may implicitly cause related models to become dirty. For example, dirtying the head of a service instance chain may cause the whole chain to be dirtied. This behavior is dependent on the model. For models that do not implement syncsteps or policies and do not have the side-effect of dirtying related models, the
setdirtycommand has no practical value, and the models may remain in perpetual dirty state.
cordctl allows you to create and restore backups of the XOS data model. XOS backups are performed inside of the xos core container and include all live data in the data model. Backups are stored in a single file, which is downloaded to or uploaded from the pc running cordctl automatically.
To create a backup, use the backup create command. For example,
cordctl backup create mybackup
This creates a backup and downloads it to the local file mybackup on your computer. If a simple filename or relative path is used, the backup is automatically stored relative to the current working directory. You may use an absolute path to store the file elsewhere. Creating the backup may take some time, and cordctl will emit some progress information during the process.
Restoring the backup uses a similar command. For example,
cordctl backup restore mybackup
This uploads the file mybackup to XOS and then instructs XOS to restore that file. Upon successful completion of the restore, all existing data in the data model will be replaced by the contents of the restore file.
To run unit tests, go-junit-report and gocover-obertura tools must be installed. One way to do this is to install them with go get, and then ensure your GOPATH is part of your PATH (editing your ~/.profile as necessary).
go get -u github.com/jstemmer/go-junit-report go get -u github.com/t-yuki/gocover-cobertura