Cisco Elastic Services Controller Installer Arguments

You need to specify the following bootvm.py script arguments to boot ESC instances.

Arguments

Description

esc_hostname

Specifies the host name of the ESC VM instance.

--image

Specifies the image id used in the OpenStack glance to boot up the ESC instance.

--boot_volume

Specify the volume name or id of the external bootable volume from where you want to launch ESC instance.

--net

Specifies the Network IDs or names in OpenStack that ESC connects to.

--ipaddr

(Optional) Specifies the IP addresses that ESC will be assigned in the network.
Note 

The IP address must correspond to the net_id in the --net argument.

--gateway_ip

(Optional) Specifies the default gateway IP address of ESC.

--os_auth_url

(Optional) Specifies the OpenStack keystone url used by os_auth_url for authentication.

--os_username

(Optional) Specifies the OpenStack keystone username used by os_username for authentication.

--os_password

(Optional) Specifies the OpenStack keystone password used by os_password for authentication.

--os_tenant_name

(Optional) Specifies the OpenStack tenant name used by os_tenant_name for ESC deployment.

--bs_os_auth_url

(Optional) Specifies the OpenStack keystone url used by bs_os_auth_url for authentication.

--bs_os_username

(Optional) Specifies the OpenStack keystone username used by bs_os_username for authentication.

--bs_os_password

(Optional) Specifies the OpenStack keystone password used by bs_os_password for authentication.

--bs_os_tenant_name

(Optional) Specifies the OpenStack tenant name used by bs_os_tenant_name for ESC deployment.

--flavor

(Optional) Specifies the OpenStack flavor id to boot the ESC VM.

--security_rules_file

(Optional) Specifies the file to define security rules (IP, Port security) for ESC VM.

--etc_hosts_file

(Optional) Specifies the file for adding more entries to the ESC vm's hosts file (/etc/hosts).

--avail_zone

(Optional) Specifies the OpenStack zone used for ESC deployment.

--esc_params_file

(Optional) Specifies the default parameter file for ESC deployment.

--db_volume_id

(Optional) Specifies the cinder volume id to mount for database storage in ESC HA [ESC-HA].

-- ha_node_list

(Optional) Specifies list of IP addresses for HA nodes in the Primary/Standby cluster. For ESC nodes with multiple network interfaces, these IPs should be the addresses in the network used for data synchronization.
Note 

This argument is utilized for replication-based HA solution only.

--kad_vip

(Optional) Specifies the IP address for Keepalived VIP (virtual IP) plus the interface of Keepalived VIP [ESC-HA].

An example format for specifying the interface of VIP is --kad_vip 192.0.2.1:eth2 or --kad_vip [2001:cc0:2020::fc]:eth2

--kad_vif

(Optional) Specifies the interface for Keepalived virtual IP and keepalived VRRP [ESC-HA]. You can also use this argument to only specify the interface for Keepalived VRRP, if the VIP interface is already specified using the kad_vip argument.

--kad_vri

Specified the virtual router id of vrrp instance. Accepted values for kad_vri are 0 to 254. ESC VMs in the same HA should use the same kad_vri number. If kad_vip is not used for L3 HA, the kad_vir has to be used, otherwise, you can skip kad_vri argument.

--route

Specifies the routing configuration for ESC VM.

--ntp_server

(Optional) Specifies the NTP server address.

--rsyslog_server

(Optional) Specifies the IP address of rsyslog server that ESC sends the log to

--rsyslog_server_port

(Optional) Specifies the port of rsyslog server that ESC sends the log to.

--rsyslog_server_protocol

(Optional) Specifies the protocol to be used by the ESC to forward logs to the server.

--secure

(Optional) Enables secure configuration. You can specify the following values:

  • A—Root is completely locked out. You cannot login as a root even from the console.

  • B—SELinux runs in the enforcing mode.

  • C—IPv4/IPv6 tables are started.

  • D—SSH password authentication is disabled. You need the private key to ssh into ESC vm.

  • E—host keys for confd will be re-created.

--host_mapping_file

(Optional) Specifies the host mapping file for VNF deployment.

--version

(Optional) Prints the version of bootvm.py and exits.

--rng_virtio

Enables installing and deploying the ESC VM on Libvirt/KVM with the RNG Virtio device. The default values are: device=/dev/random rate_period=1000 rate_bytes=1024

--user_pass

This along with --user_confd_pass are mandatory arguments from 3.0 onwards.

This argument adds a user to access the ESC VM. Use this argument to specify a user without administrative privileges, i.e, a non-admin/non-root user. Use the following format: user_name:password. The bootvm.py command requires at least one --user_pass argument to create an admin account for linux (ssh/console access) . The following is the syntax for the mandatory user credential argument: 

--user_pass
admin:'PASSWORD-OR-HASH'[:OPTIONAL-PUBLIC-KEY-FILE][:OPTIONAL-ROLE]
This user can only do the following:
  • Login to ESC through SSH.
  • Access and drive the Netconf CLI, such as, esc_nc_cli, netconf-console, and so on.
  • Read ESC -related logs from /var/logs/esc
  • Access REST interface through localhost
This user cannot:
  • Access the ESC DB and reconfigure ESC system.
  • Access the system-level logs
  • Configure the system level components, such as: Rsyslog, Keepalived, DRDB, and so on.
  • Access the encryption keys and values from REST interface or ESC logs.

Following is an example of --user_pass for admin account and stronger clear text passwords. Use single quotes to avoid conflict with shell reserved characters:

-user_pass admin:'Strong4Security!'.

Another example to install ESC using a password hash for both admin accounts. Use single quotes to avoid conflict with shell reserved characters:

--user_pass admin:'$algorithm$salt$hash-of-salt-password'.

ESC 2.1 and later, accepts the public key for this attribute. For example, the following will generate 'admin321' as the password for user 'admin' and use /tmp/abc.pub as the key file to inject the public key for it: 

--user_pass
admin:admin321:/tmp/abc.pub

--user_confd_pass

Used to change confd users. The bootvm.py command requires at least one --user_confd_pass to create an admin account for ConfD (netconf/cli access). The following is the syntax for the mandatory user credential argument: 

--user_confd_pass admin:'PASSWORD-OR-HASH'[:OPTIONAL-PUBLIC-KEY-FILE]

Following is an example of --user_confd_ pass for admin account and stronger clear text passwords. Use single quotes to avoid conflict with shell reserved characters:

--user_confd_ pass:'Strong4Security!'.

Another example, to install ESC using a password hash for both admin accounts. Use single quotes to avoid conflict with shell reserved characters:

--user_confd_ pass:'$algorithm$salt$hash-of-salt-password'.

ESC 2.1 and later, accepts the public key for this attribute. For example, the following will generate 'admin321' as the password for user 'admin' and use /tmp/abc.pub as the key file to inject the public key for it: --user_confd_ pass:admin321:/tmp/abc.pub

--esc_portal_startup

(Optional) Starts the ESC portal.

--log

(Optional) Specifies the log file. By default, logs to stdout.

--esc_monitor_check_ips

(Optional) Specifies the IP addresses that must be monitored by esc_monitor (for HA failover).

--enable-https-rest

(Optional) Enables a secure REST Interface for the created ESC VM.

--enable-http-rest

(Optional) Enables an unsecured REST Interface for the created ESC VM.

--disable-rest-auth

(Optional) Disables REST API authentication.

Note 
 REST authentication should not be disabled in a production environment.

--enable-snmp-agent

(Optional) Enables automatic start-up of the SNMP service. The default value is False.

--ha_mode

Specifies the ESC HA mode for HA installation. Specify one of the following available options for HA: no_ha: No HA, cinder: Shared Cinder Volume, drbd: Built-in DRBD, drbd_on_cinder: DRBD over Cinder Volume

--enable-https-etsi

(Optional) Enables a secure ETSI REST Interface for the created ESC VM.

--enable-http-etsi

 (Optional) Enables an unsecured ETSI REST Interface for the created ESC VM. Enabling this interface is not recommended in a production environment.

--encrypt_key

Specifies the key for encryption.

--proxy

Uses the proxy on a given port.

--noproxy

Lists the hosts which do not use proxy.

--kad_unicast_src_ip

Specifies the source IP address of unicast. Should be the IP address of interface that ESC VM uses for unicast (L3) VRRP communication.

Example: --kad_unicast_src_ip 10.0.0.1

--kad_unicast_peer

Specified the peer IP addresses of unicast. Should be the ip address of interface that ESC peer VM uses for unicast (L3) VRRP communication.

Example: --kad_unicast_peer 10.0.0.1

--placement_hint

Use this argument to specify the placement of ESC HA virtual machines using the server group, samehost, differenthost filters.

Example:
  • --placement_hint different_host=2b299428-e7a7-4528-8566-9a4970183c6a [ID should be the VM uuid]
  • --placement_hint same_host=2b299428-e7a7-4528-8566-9a4970183c6a [ID should be the VM uuid]
  • --pacement_hint group=4c7758ab-e9cb-4cf0-8f02-344ec666365b [ID should be the server group uuid]

--format {json}

Use this argument to capture the success and failure message in the output.

Example: $ ./bootvm.py --image ESC-2_3_0_8 --net network --format json --test-0

{ "status" : "Success" , "vm_uuid" : "UUID" }

--user_rest_pass

Adds a user to access the Rest API. Format is username: password. This option can be repeated.

--user_portal_pass

Add a portal user. Format username: password. This option can be repeated.

--user_etsi_pass

Adds a user to access the ETSI REST API. Format username:password. This option can be repeated.

--no_vim_credentials

Use this argument to deploy ESC without passing the VIM credential. If this argument is used, following parameters will not be passed during the installation:

  • --os_auth_url

  • --os_username

  • --os_password

  • --os_tenant_name

After the deployment is complete, the user can set these VIM credential through ESC's VIM/VIM User APIs (REST/Netconf). For more information on configuring through REST APIs and Netconf, see Configuring VIM credentials after installing ESC in the Post Installation Tasks chapter.

--etsi_startup

This argument is deprecated in ESC 4.4 and above, it is unavailable in future releases. The use of --etsi_startup shows an error message with the appropriate replacement argument to use. See --enable-etsi-http and --enable-etsi-https.

Cisco Elastic Services Controller Installer File Reference

File

Description

security_rules_file

The file contains the following:

  • Security rules to create a security group for the tenant.

  • Configurations to allow traffic for the tenant.

etc_hosts_file

The file contains one or more entries that you want to include in the /etc/hosts file.

esc_params_file

The file contains information to configure various parameters of ESC. For details on parameters that can be configured in the esc_params_file are described in table below.

host_mapping_file

The file contains information to map a network based on the hosts.

ESC Configuration Parameters

Using this file, you can configure various ESC parameters during the installation. The parameters that can be configured are shown in the table.

Below is an example configuration using this file: 
openstack.endpoint=adminURL
affinity.filter=ServerGroupAffinity
Table 1. ESC Configuration Parameters

esc_param.conf

Type

Default Value

Description

default.vm_recovery_retries_max Int 3

Number of recovery attempts allowed per VM.

openstack.endpoint String publicURL

The parameter to set up the keystone endpoint value of ESC. Options: adminURL, publicURL

You can change the default value using CLI or REST services.

Using CLI: 

$ sudo escadm escmanager config set --key openstack.endpoint 
--value publicURL
{
    "category": "OPENSTACK",
    "type": "STRING",
    "value": "publicURL",
    "key": "ENDPOINT"
}
Using REST: 

$ curl -X PUT http://172.16.0.1:8080/ESCManager/v0/config
/openstack/endpoint/publicURL
log.level String INFO

Level of logging. Options: INFO, Trace, DEBUG

affinity.filter String SameHostFilter

A constant string used to build PolicyEngine and initializing VM policy table.

Options: SameHostFilter, ServerGroupAffinity

anti_affinity.filter String DifferentHostFilter

A constant string used to build PolicyEngine and initializing VM policy table.

Options: DifferentHostFilter


Note
ESC uses SameHostFilter and DifferentHostFilter for ESC policy engine by default but OpenStack may not configure those filters by default. You may need to add SameHostFilter and DifferentHostFilter to the following scheduler options in the /etc/nova/nova.conf file of the nova service in your OpenStack. 
scheduler_default_filters = RetryFilter, AvailabilityZoneFilter,RamFilter, ComputeFilter, ComputeCapabilitiesFilter,
ImagePropertiesFilter, ServerGroupAntiAffinityFilter, ServerGroupAffinityFilter, DifferentHostFilter, SameHostFilter

ServerGroupAntiAffinityFilter for Openstack

ESC adapts to use ServerGroupAntiAffinityFilter for Openstack.

REST

PUThttp://localhost:8080/ESCManager/v0/config/anti_affinity/filter/ServerGroupAntiAffinity

PUThttp://localhost:8080/ESCManager/v0/config/affinity/filter/ServerGroupAffinity

CLI

sudo escadm escmanager config set --key ANTI_AFFINITY.FILTER --value ServerGroupAntiAffinity
sudo escadm escmanager config set --key AFFINITY.FILTER --value ServerGroupAffinity

Important Points

ServerGroupAntiAffinityFilter from Openstack doesn't support inter-dep anti-affinit, scaling, and mix use of ServerGroup and default (SameHost/DifferentHost) filter. If you are using ServerGroupAntiAffinity filter, Intra vm group placement is not allowed. You can only use <placement_group> for the VM based placement policy, one VM per vm_group. You can not add a single vm group in two different placement_groups.