configchannel

Available methods

Description

Provides methods to access and modify many aspects of configuration channels.

Namespace:

configchannel

Method: channelExists

HTTP POST

Description:

Check for the existence of the config channel provided.

Parameters:

  • string sessionKey

  • string label - channel to check for

Returns:

  • int existence - 1 if exists, 0 otherwise

Method: create

HTTP POST

Description:

Create a new global config channel. Caller must be at least a config admin or an organization admin.

Parameters:

  • string sessionKey

  • string label

  • string name

  • string description

Returns:

  • * struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: create

HTTP POST

Description:

Create a new global config channel. Caller must be at least a config admin or an organization admin.

Parameters:

  • string sessionKey

  • string label

  • string name

  • string description

  • string type - the channel type either 'normal' or 'state'

Returns:

  • * struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: create

HTTP POST

Description:

Create a new global config channel. Caller must be at least a config admin or an organization admin.

Parameters:

  • string sessionKey

  • string label

  • string name

  • string description

  • string type - the channel type either 'normal' or 'state'

  • struct pathInfo - the path info

    • string "contents" - contents of the init.sls file

    • boolean "contents_enc64" - identifies base64 encoded content(default: disabled)

Returns:

  • * struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: createOrUpdatePath

HTTP POST

Description:

Create a new file or directory with the given path, or update an existing path.

Parameters:

  • string sessionKey

  • string label - the channel label

  • string path

  • boolean isDir - true if the path is a directory, False if it is a file

  • struct pathInfo

    • string "contents" - contents of the file (text or base64 encoded if binary or want to preserve control characters like LF, CR etc.)(only for non-directories)

    • boolean "contents_enc64" - identifies base64 encoded content (default: disabled, only for non-directories)

    • string "owner" - owner of the file/directory

    • string "group" - group name of the file/directory

    • string "permissions" - octal file/directory permissions (eg: 644)

    • string "selinux_ctx" - SELinux Security context (optional)

    • string "macro-start-delimiter" - config file macro start delimiter. Use null or empty string to accept the default. (only for non-directories)

    • string "macro-end-delimiter" - config file macro end delimiter. Use null or empty string to accept the default. (only for non-directories)

    • int "revision" - next revision number, auto increment for null

    • boolean "binary" - mark the binary content, if True, base64 encoded content is expected (only for non-directories)

Returns:

  • * struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.

Available since API version: 10.2

HTTP POST

Description:

Create a new symbolic link with the given path, or update an existing path in config channel of 'normal' type.

Parameters:

  • string sessionKey

  • string label

  • string path

  • struct pathInfo

    • string "target_path" - the target path for the symbolic link

    • string "selinux_ctx" - SELinux Security context (optional)

    • int "revision" - next revision number, skip this field for automatic revision number assignment

Returns:

  • * struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.

Available since API version: 10.2

Method: deleteChannels

HTTP POST

Description:

Delete a list of global config channels. Caller must be a config admin.

Parameters:

  • string sessionKey

  • string array labels - configuration channel labels to delete

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: deleteFileRevisions

HTTP POST

Description:

Delete specified revisions of a given configuration file

Parameters:

  • string sessionKey

  • string label - label of config channel to lookup on

  • string filePath - configuration file path

  • int array revisions - list of revisions to delete

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: deleteFiles

HTTP POST

Description:

Remove file paths from a global channel.

Parameters:

  • string sessionKey

  • string label - channel to remove the files from

  • string array paths

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: deployAllSystems

HTTP POST

Description:

Schedule an immediate configuration deployment for all systems subscribed to a particular configuration channel.

Parameters:

  • string sessionKey

  • string label - the configuration channel’s label

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: deployAllSystems

HTTP POST

Description:

Schedule a configuration deployment for all systems subscribed to a particular configuration channel.

Parameters:

  • string sessionKey

  • string label - the configuration channel’s label

  • dateTime.iso8601 date - the date to schedule the action

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: deployAllSystems

HTTP POST

Description:

Schedule a configuration deployment of a certain file for all systems subscribed to a particular configuration channel.

Parameters:

  • string sessionKey

  • string label - the configuration channel’s label

  • string filePath - the configuration file path

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: deployAllSystems

HTTP POST

Description:

Schedule a configuration deployment of a certain file for all systems subscribed to a particular configuration channel.

Parameters:

  • string sessionKey

  • string label - the configuration channel’s label

  • string filePath - the configuration file path

  • dateTime.iso8601 date - the date to schedule the action

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: getDetails

HTTP GET

Description:

Lookup config channel details.

Parameters:

  • string sessionKey

  • string label

Returns:

  • * struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: getDetails

HTTP GET

Description:

Lookup config channel details.

Parameters:

  • string sessionKey

  • int id - the channel ID

Returns:

  • * struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: getEncodedFileRevision

HTTP GET

Description:

Get revision of the specified configuration file and transmit the contents as base64 encoded.

Parameters:

  • string sessionKey

  • string label - label of config channel to lookup on

  • string filePath - config file path to examine

  • int revision - config file revision to examine

Returns:

  • * struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.

Method: getFileRevision

HTTP GET

Description:

Get revision of the specified config file

Parameters:

  • string sessionKey

  • string label - label of config channel to lookup on

  • string filePath - config file path to examine

  • int revision - config file revision to examine

Returns:

  • * struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.

Method: getFileRevisions

HTTP GET

Description:

Get list of revisions for specified config file

Parameters:

  • string sessionKey

  • string label - label of config channel to lookup on

  • string filePath - config file path to examine

Returns:

  • array :

  • struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.

Method: listAssignedSystemGroups

HTTP GET

Description:

Return a list of Groups where a given configuration channel is assigned to

Parameters:

  • string sessionKey

  • string label - label of the config channel to list assigned groups

Returns:

  • array :

  • struct server group

    • int "id"

    • string "name"

    • string "description"

    • int "org_id"

    • int "system_count"

Method: listFiles

HTTP GET

Description:

Return a list of files in a channel.

Parameters:

  • string sessionKey

  • string label - label of config channel to list files on

Returns:

  • array :

  • struct configuration file information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • dateTime.iso8601 "last_modified" - Last Modified Date

Method: listGlobals

HTTP GET

Description:

List all the global config channels accessible to the logged-in user.

Parameters:

  • string sessionKey

Returns:

  • array :

  • struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • string "type"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: listSubscribedSystems

HTTP GET

Description:

Return a list of systems subscribed to a configuration channel

Parameters:

  • string sessionKey

  • string label - label of the config channel to list subscribed systems

Returns:

  • array :

  • struct system

    • int "id"

    • string "name"

Method: lookupChannelInfo

HTTP GET

Description:

Lists details on a list of channels given their channel labels.

Parameters:

  • string sessionKey

  • string array labels - the channel labels

Returns:

  • array :

  • struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: lookupFileInfo

HTTP GET

Description:

Given a list of paths and a channel, returns details about the latest revisions of the paths.

Parameters:

  • string sessionKey

  • string label - label of config channel to lookup on

  • string array paths - list of paths to examine

Returns:

  • array :

  • struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.

Available since API version: 10.2

Method: lookupFileInfo

HTTP GET

Description:

Given a path, revision number, and a channel, returns details about the latest revisions of the paths.

Parameters:

  • string sessionKey

  • string label - label of config channel to lookup on

  • string path - path of file/directory

  • int revision - the revision number

Returns:

  • * struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.

Available since API version: 10.12

Method: scheduleFileComparisons

HTTP POST

Description:

Schedule a comparison of the latest revision of a file against the version deployed on a list of systems.

Parameters:

  • string sessionKey

  • string label - label of config channel

  • string path - file path

  • long array sids

Returns:

  • int actionId - the action ID of the scheduled action

Method: syncSaltFilesOnDisk

HTTP POST

Description:

Synchronize all files on the disk to the current state of the database.

Parameters:

  • string sessionKey

  • string array labels - configuration channel labels to synchronize files from

Returns:

  • int - 1 on success, exception thrown otherwise.

Method: update

HTTP POST

Description:

Update a global config channel. Caller must be at least a config admin or an organization admin, or have access to a system containing this config channel.

Parameters:

  • string sessionKey

  • string label

  • string name

  • string description

Returns:

  • * struct configuration channel information

    • int "id"

    • int "orgId"

    • string "label"

    • string "name"

    • string "description"

    • struct "configChannelType"

  • struct configuration channel type information

    • int "id"

    • string "label"

    • string "name"

    • int "priority"

Method: updateInitSls

HTTP POST

Description:

Update the init.sls file for the given state channel. User can only update contents, nothing else.

Parameters:

  • string sessionKey

  • string label - the channel label

  • struct pathInfo

    • string "contents" - contents of the init.sls file

    • boolean "contents_enc64" - identifies base64 encoded content(default: disabled)

    • int "revision" - next revision number, auto increment for null

Returns:

  • * struct configuration revision information

    • string "type"

      • file

      • directory

      • symlink

    • string "path" - File Path

    • string "target_path" - Symbolic link Target File Path. Present for Symbolic links only.

    • string "channel" - Channel Name

    • string "contents" - File contents (base64 encoded according to the contents_enc64 attribute)

    • boolean "contents_enc64" - Identifies base64 encoded content

    • int "revision" - File Revision

    • dateTime.iso8601 "creation" - Creation Date

    • dateTime.iso8601 "modified" - Last Modified Date

    • string "owner" - File Owner. Present for files or directories only.

    • string "group" - File Group. Present for files or directories only.

    • int "permissions" - File Permissions (Deprecated). Present for files or directories only.

    • string "permissions_mode" - File Permissions. Present for files or directories only.

    • string "selinux_ctx" - SELinux Context (optional).

    • boolean "binary" - true/false , Present for files only.

    • string "sha256" - File’s sha256 signature. Present for files only.

    • string "macro-start-delimiter" - Macro start delimiter for a config file. Present for text files only.

    • string "macro-end-delimiter" - Macro end delimiter for a config file. Present for text files only.