com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'html' is unknown.

XpoLog SDK

General

XpoLog SDK provides a set of commands that enables remote configuration of different XpoLog properties without accessing the GUI.

The following commands are available.

Connection

Settings

  • Ports (HTTP, SSL, SHUTDOWN and AJP)
  • Enable/Disable Security
  • Enable/Disable Agent Mode

Security

  • Add/Edit user

Accounts Management

  • Add/Edit/Remove/Enable/Disable remote XpoLog account
  • Add/Edit/Remove/Enable/Disable SSH account
  • Add/Edit/Remove/Enable/Disable AWS S3 account

Tasks Management

  • Add/Edit/Execute Add Logs Directory task
  • Add/Edit/Execute LogSync task

Folders and Logs Management

  • Add Log
  • Add Folder
  • Remove existing folder/log

AppTags

  • Apply a Time Zone for AppTags

Restart

Apply License

Apply Patch

Requirements

  • XpoLog Client Jar (download here)
  • XpoLog keystore file - mandatory when using HTTPS, extract the zip at the same directory of the xpologClient.jar file and ensure a file .keystore exists in the location after extraction (download here)
  • JAVA on client machine that executes the commands
  • Connectivity (HTTP/S) between the client machine that executes the commands to the XpoLog server

Syntax

Connection


In order to execute remote commands it is first required to provide connection parameters to the XpoLog instance:

Connection Parameters

Key

Description

Values

 

xpologURL

The URL to the XpoLog instance

URL

Mandatory

user

Authentication user name

Text

Optional (Mandatory if security is enabled)

password

Authentication password

Text

Optional (Mandatory if security is enabled)

 

Example of base command to connect to a remote XpoLog:

java -cp xpologClient.jar com.xpolog.sdk.client.XpoLogSDKClient -xpologURL http://<xpolog-machine>:<xpolog-port>/logeye -user USER_NAME -password PASSWORD

 

When using scripts, it is recommended to set the above as parameters, as they should be used on any command which is being executed:

Windows:

set JAVA_RUN=java -cp xpologClient.jar com.xpolog.sdk.client.XpoLogSDKClient

set XPOLOG_CONN=-xpologURL http://<xpolog-machine>:<xpolog-port>/logeye -user USER_NAME -password PASSWORD

Linux:

JAVA_RUN=”java -cp xpologClient.jar com.xpolog.sdk.client.XpoLogSDKClient”

XPOLOG_CONN=”-xpologURL http://<xpolog-machine>:<xpolog-port>/logeye -user USER_NAME -password PASSWORD”

 

After a connection is established the following command may be executed against the connected XpoLog instance:

 

General Settings and Security Commands

Settings Parameters

Key

Description

Values

 

api

The API type to use – must be settings

“settings”

Mandatory

httpPort

The HTTP port XpoLog is listening on

Number

Optional

sslPort

The SSL port XpoLog is listening on

Number

Optional

shutdownPort

The server’s shutdown port

Number

Optional

ajpPort

The server’s ajp port

Number

Optional

agentMode

Enable/Disable agent mode

true/false

Optional

activateSecurity

Enable/Disble security

true/false

Optional

activateSystemTimeZone

Set the XpoLog's user Time Zone Mode to System (Default)

true/falseOptional
activateDynamicTimeZone

Set the XpoLog's user Time Zone Mode to Dynamic

true/falseOptional
activateAppTagsTimeZone

Set the XpoLog's user Time Zone Mode to per AppTags

true/falseOptional

 

Example of configuring ports:

%JAVA_RUN% %XPOLOG_CONN% -api settings -httpPort 30304 -sslPort 30444 -ajpPort 8010 -shutdownPort 8096 -agentMode true -activateSecurity true

Example of changing system time zone mode:

%JAVA_RUN% %XPOLOG_CONN% -api settings -activateAppTagsTimeZone true

 

 Security Users Parameters

Key

Description

Values

 

api

The API type to use – must be securityUsers

“securityUsers”

Mandatory

name

The user name of the user

Text

Mandatory

userPassword

The user password

Text

Mandatory for new

displayName

The display name of the user

Text

Mandatory for new

override

Override an existing user (Default: false)

true/false

Optional

userPolicy

The policy name to associate to this user

Text

Optional

selectedGroupsList

The names of the selected groups to associate with this user

Text List (separate by ;)

Optional

 

Example of adding a new user and setting its properties:

%JAVA_RUN% %XPOLOG_CONN% -api securityUsers -name testUser -userPassword testPassword -displayName "TEST USER" -override true -userPolicy test -selectedGroupsList testgroup;All


 

 

Accounts Management

Remove Account

Key

Description

Values

 

api

The API type to use – must be removeAccount

“removeAccount”

Mandatory

name

The name of the account to be removed

Text

Mandatory

Example of removing an account:

%JAVA_RUN% %XPOLOG_CONN% -api removeAccount -name "ACCOUNT_NAME"


Disable/Enable Account

Key

Description

Values

 

api

The API type to use – must be enableAccount

“enableAccount”

Mandatory

name

The name of the account to be removed

Text

Mandatory

enabled

Enable/Disable the account

true/false

Mandatory

Example of disabling an account:

%JAVA_RUN% %XPOLOG_CONN% -api enableAccount -name "ACCOUNT_NAME" -enabled false

Add SSH Account Parameters

Key

Description

Values

 

api

The API type to use – must be addSSHAccount

“addSSHAccount”

Mandatory

name

The name of the account

Text

Mandatory

descriptionThe description of the accountTestOptional

hostName

Host Name

Text

Mandatory for new

conType

The connection type (Default: SFTP)

SFTP/SCP

Optional

portThe port to be used in the account (Default: 22)NumberOptional

override

Override an existing account (Default: false)

true/false

Optional

enabled

Enable/Disable the account

true/false

Optional

privateKeyPath 

Full Path to Key

Text

Optional

username

Authentication user name

Text

Optional

userPassword

Authentication password

Text

Optional

 

Example for adding an SSH account:

%JAVA_RUN% %XPOLOG_CONN% -api addSSHAccount -name "ACCOUNT_NAME" -hostName MACHINE_IP -conType SFTP -port 22 -override true -enabled true -privateKeyPath "" -username USER_NAME -userPassword PASSWORD


Add Remote XpoLog Account Parameters

Key

Description

Values

 

api

The API type to use – must be addRemoteXpoLogAccount

“addRemoteXpoLogAccount”

Mandatory

name

The name of the account

Text

Mandatory

descriptionThe description of the accountTestOptional

hostName

Host Name

Text

Mandatory for new

conType

The connection type (Default: HTTP)

HTTP/HTTPS

Optional

override

Override an existing account (Default: false)

true/false

Optional

enabled

Enable/Disable the account

true/false

Optional

isCollected

False – Proxy mode, True – Agent Mode (Default: true)

true/false

Optional

username

Authentication user name

Text

Optional

userPassword

Authentication password

Text

Optional

 

Example of adding a remote XpoLog account:

%JAVA_RUN% %XPOLOG_CONN% -api addRemoteXpoLogAccount -name "ACCOUNT_NAME" -hostName MACHINE_IP -conType HTTP -port 30303 -context logeye -override true -enabled true -isCollected true -username admin -userPassword admin


Add AWS S3 Account Parameters

Key

Description

Values

 

api

The API type to use – must be addExternalAccount

“addExternalAccount”

Mandatory

name

The name of the account

Text

Mandatory

descriptionThe description of the accountTextOptional

externalMediaType

The type of the account

s3

Mandatory (lowercase only)

ema_custom_accessKeyThe AWS S3 access keyTextMandatory
ema_custom_secretKeyThe AWS S3 secret keyTextMandatory

override

Override an existing account (Default: false)

true/false

Optional

enabled

Enable/Disable the account

true/false

Optional

 

Example for adding an SSH account:

%JAVA_RUN% %XPOLOG_CONN% -api addExternalAccount -externalMediaType "s3" -name "ACCOUNT_NAME" -description "ACCOUNT_DESCRIPTION" -override true -ema_custom_accessKey "ACCOUNT_ACCESS_KEY" -ema_custom_secretKey "ACCOUNT_SECRET_KEY"

Tasks Management

Execute Task Parameters

Key

Description

Values

 

api

The API type to use – must be executeTask 

“executeTask”

Mandatory

name

The name of the task (case sensitive)

Text

Mandatory

Example for executing a task:

%JAVA_RUN% %XPOLOG_CONN% -api executeTask -name "TASK_NAME"


Execution of a Logs Directory Task (Scanner)

Key

Description

Values

 

api

The API type to use – must be executeScanTask

“executeScanTask”

Mandatory

name

The name of the task to be presented in XpoLog logs / Activity console while running (recommended)

Text

Optional

id

The id of the task - used to avoid re-creation of logs which were already created by a SDK command (recommended)

Text

Optional

parentFolderPath

Determines under which folder to create/update logs that are created by the SDK command (Default: Folders and Logs). Folder is created if does not exist

ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between folders

Optional

accountName

The connectivity account to use if the scan is not local

Text

Mandatory for SSH

scanPath 

The full path to scan (local or on the remote source after connection is established)

Text

Mandatory

Scan Parameters

The SDK supports all the 'ScanConfiguration' parameters
Use -PARAM_NAME PARAM_VALUE in the command 

Text

Optional

 

Example of executing a scan directory operation:

%JAVA_RUN% %XPOLOG_CONN% -api executeScanTask -name "SCANNER_SDK" -id "SCAN12345" -parentFolderPath "ROOT->NEW_PARENT_FOLDER-accountName ACCOUNT_NAME -scanPath "/var/log/" -scanMethod 0 -timeZone GMT -directoriesToInclude "DIR1,DIR2" -filesToExclude "*.zip,*.gzip,*.tar*"

Add Logs Directory Task (Scanner)

Key

Description

Values

 

api

The API type to use – must be executeScanTask

“addScanTask”

Mandatory

name

The name of the task to be presented in XpoLog logs / Activity console while running (recommended)

Text

Optional

id

The id of the task - used to avoid re-creation of logs which were already created by a SDK command (recommended)

Text

Optional

parentFolderPath

Determines under which folder to create/update logs that are created by the SDK command (Default: Folders and Logs). Folder is created if does not exist

ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between folders

Optional

accountName

The connectivity account to use if the scan is not local

Text

Mandatory for SSH

scanPath 

The full path to scan (local or on the remote source after connection is established)

Text

Mandatory

Scan Parameters

The SDK supports all the 'ScanConfiguration' parameters
Use -PARAM_NAME PARAM_VALUE in the command 

Text

Optional

cron

Unix cron expression format

cron expression format     

Optional

override

Override an existing task (Default: false)

true/false

Optional

                                            

Example of adding a scan directory task:

%JAVA_RUN% %XPOLOG_CONN% -api addScanTask -name "SCANNER_SDK" -id "SCAN12345" -parentFolderPath "ROOT->NEW_PARENT_FOLDER" -accountName ACCOUNT_NAME -scanPath "/var/log/" -scanMethod 0 -timeZone GMT -directoriesToInclude "DIR1,DIR2" -filesToExclude "*.zip,*.gzip,*.tar*" -cron "0 * * * * ? *" -assignedCollectionPolicy “Default"


Add Log Sync Task Parameters

Key

Description

Values

 

api

The API type to use – must be addSyncLogTask

“addSyncLogTask”

Mandatory

name

The name of the task

Text

Mandatory

configFilePath

The absolute path to the LogSync configuration file to be used by this task

Text

Mandatory

createConfiguration

Determines whether to create Folders and Logs configuration from the synched logs (Default: false)

true/false

Optional

parentFolderPath

The parent folder path of this task’s result. Folder and Logs is the default path.

Use ‘->’ in the path between folders

Optional

cron

Unix cron expression format

cron expression format

Optional

assignedNode

The name of the XpoLog node to be assigned on this task

Text

Optional

override

Override an existing task (Default: false)

true/false

Optional

 

Example of adding a Log Sync task:

%JAVA_RUN% %XPOLOG_CONN% -api addSyncLogTask -name "New Log Sync Test" -configFilePath C:\dev\syncLogsTest.xml -override true  -cron "0/10 * * * * ? *"

Folders and Logs Management

Add Log

Key

Description

Values

 

api

The API type to use – must be addLog

“addLog”

Mandatory

logNameThe name of the log to be createdTextMandatory
logPathThe full path to the log under the Folders and Log Tree (excluding the log name)ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between foldersOptional
newLogPaththe new Folders and Logs path to placethe log in XpoLog Folders and Logs tree (for example Root->Folder1->Folder2).ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between foldersOptional*
  • If used override must be true
  • If used newLogName must not be used
newLogNamethe new log nameTextOptional*
  • If used override must be true
  • If used newLogPath must not be used

filesPath

The full path to the logs on the source:

  • SSH\Windows\Local - absoulute path to the files on the source (name pattern may be used)
  • Remote XpoLog Log - the filesPath parameter should be the path of the log under the Folders and Logs tree in the Remote XpoLog instance to be added (for example Root->Folder1->Folder2->log1).

Text

Mandatory

collectionPolicyThe exact name of the collection policy to be assigned on the log (if doesn't exist, the command will be ignored)TextOptional
accountNameThe name of the account to be used if needed (SSH or Win Account or Remote XpoLog)TextDirect Access - Optional
Win Network/SSH - Mandatory 
patternsA list of patterns that will be applied on the log that is added (separated by XPLG_SDK_SEP)Text

Mandatory*
If a template is used - optional 

appTagsA comma separated list of appTags that the added log will be tagged toTextOptional
overrideAppTagsspecifies whether to add appTags on a log or replace the existing appTags of a log. Used only on edit when override is set to truetrue/falseOptional
timezoneThe timezone definition of the added logText (a value from JAVA time zone list)Optional
charsetThe charset definition of the added logText (a value from JAVA charset list)Optional
templateThe name of the template to be usedTextOptional*
specific parameters that are passed override template's settings 
dataFilterQueryThe dataFilterQuery to be applied on the specified - see Advanced Log Settings for more information. (pass an empty filter to clear an existing filter)TextOptional

override

Overwrite an existing log configuration (Default: false)

true/false

Optional

Example of adding a log:
%JAVA_RUN% %XPOLOG_CONN% -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -filesPath "c:\LogFiles\messages{string}-patterns " {date:Date,dd/MM/yyyy HH:mm:ss.SSSSSS} {text:priority} {string:message}XPLG_SDK_SEP{date:Date,dd/MM/yyyy HH:mm:ss.SSS} {text:priority} {string:message}-appTags "APP_TAG_NAME_1,APP_TAG_NAME_2"

Example of adding a log over SSH using an existing account :
%JAVA_RUN% %XPOLOG_CONN% -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -filesPath "c:\LogFiles\messages{string}" -template "LOG_TEMPLATE_NAME" -accountName "ACCOUNT_NAME"

Example of editing an existing log and replacing its AppTags:
%JAVA_RUN% %XPOLOG_CONN% -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -appTags "APP_TAG_NAME_1,APP_TAG_NAME_2" -override "true" -overrideAppTags "true"  

Example of renaming an existing log in XpoLog from LOG_EXAMPLE to LOG_EXAMPLE_NEW:
%JAVA_RUN% %XPOLOG_CONN% -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -newLogName "LOG_EXAMPLE_NEW" -override "true"  

Example of moving an existing log to be placed under 'ROOT->FOLDER_1->FOLDER_2' to 'ROOT->FOLDER_1->FOLDER_2->FOLDER_3' in XpoLog Folders and Logs tree:
%JAVA_RUN% %XPOLOG_CONN% -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -newLogPath "ROOT->FOLDER_1->FOLDER_2->FOLDER_3" -override "true" 


Add Folder

Key

Description

Values

 

api

The API type to use – must be addFolder

addFolder

Mandatory

folderPath

The full path to the folder to be added

ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between folders

Mandatory

Example for adding an empty folder:

%JAVA_RUN% %XPOLOG_CONN% -api addFolder -folderPath "ROOT->FOLDER_1->FOLDER_2->FOLDER_NAME_TO_BE_ADDED"


Remove Folder

Key

Description

Values

 

api

The API type to use – must be removeMember

“removeMember”

Mandatory

folderPath

The full path to the folder to be removed

ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between folders

Mandatory

Example for removing a folder (and all its contents):

%JAVA_RUN% %XPOLOG_CONN% -api removeMember -folderPath "ROOT->FOLDER_1->FOLDER_2->FOLDER_NAME_TO_BE_REMOVED"

 

Remove Log

Key

Description

Values

 

api

The API type to use – must be removeMember

“removeMember”

Mandatory

logPath

The full path to the log to be removed

ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between folders

Mandatory

Example for removing a folder (and all its contents):

%JAVA_RUN% %XPOLOG_CONN% -api removeMember -folderPath "ROOT->FOLDER_1->FOLDER_2->LOG_NAME_TO_BE_REMOVED"



License Parameters

Key

Description

Values

 

api

The API type to use – must be license

“license”

Mandatory

files

The path (relative to execution location or absolute path) to the license file which will be updated

Text

Mandatory

 

Example of applying a license:

%JAVA_RUN% %XPOLOG_CONN% -api license -files license.lic

 
 

AppTags Parameters

Key

Description

Values

 

api

The API type to use – must be settings

“settings”

Mandatory

appTags

A comma separated list of AppTags names (exactly as defined in XpoLog)
(The time zone will be applied only if the general User Time Zone Mode in XpoLog is set to 'AppTags') 

TextMandatory
timeZoneA single time zone from JAVA available time zones
(The time zone should be exactly as appears in the time zones list, in case XpoLog will not be able to find that given value, default system time zone will be applied automatically.
Use "Default" to apply the time zone to the system default time zone)
TextMandatory


Example of applying a time zone on an AppTag:

%JAVA_RUN% %XPOLOG_CONN% -api settings -timeZone "America/New_York" -appTags "APPTAG1, APPTAG2"

 

Restart Parameters

Key

Description

Values

 

api

The API type to use – must be restart

“restart”

Mandatory


Example of restarting XpoLog:

%JAVA_RUN% %XPOLOG_CONN% -api restart


Publish Patch Task Parameters

Key

Description

Values

 

api

The API type to use – must be addPatch

“addPatch”

Mandatory

files

The path (relative to execution location or absolute path) to the patch file

Text

Mandatory

type

Patch type – must be “api”

“api”

Mandatory

 

Example of applying a patch:

%JAVA_RUN% %XPOLOG_CONN% -api addPatch -type api -files patch.zip


Comments:

  1. Any value which contains the space character should be wrapped with “quotes”. For example if the display name of a user is TEST USER then it should wrapped with quotes as:
    ... -displayName "TEST USER" ...
  2. General Script Exampledownload here


Common Use Case:

  1. Important: in all examples above we have used %JAVA_RUN% %XPOLOG_CONN% which is suitable to Windows environments. For Linux, the SDK script should use $JAVA_RUN $XPOLOG_CONN
  2. Automatically Add Servers to XpoLog:
    Automating the process of adding new servers to XpoLog, mainly in dynamic environments such as clouds where servers are constantly added and removed. The SDK provides full support so when a new machine is added, simply be a couple of commands the new server is added to XpoLog and the required logs are be collected and available for the users. See Script Example: download here
  3. Automatically Remove / Disable Servers in XpoLog:
    1. Disable Server but keep data that was already collected
      If a server is removed from the environment but you wish to keep the data that was already collected by XpoLog from that server, simply disable the account of that specific server so XpoLog will not try to connect to it but will keep the data based on the retention policy.  See Script Example: download here
    2. Remove Server and data that was collected from it
      If a server is removed from the environment and you wish to remove it from XpoLog including all data then simply remove the account of that server and the folder which contains all its logs. See Script Example: download here