XPLG SDK

XPLG Client Jar (download here)
XPLG 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 XPLG server

Syntax

Connection

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

Connection Parameters

Key	Description	Values
xplgURL	The URL to the XPLG 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 XPLG:

java -cp xpologClient.jar com.xpolog.sdk.client.XpoLogSDKClient -xplgURL 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 XPLG_CONN=-xplgURL http://<xpolog-machine>:<xpolog-port>/logeye -user USER_NAME -password PASSWORD

Linux:

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

XPLG_CONN=”-xplgURL 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/false	Optional
activateDynamicTimeZone	Set the XpoLog's user Time Zone Mode to Dynamic	true/false	Optional
activateAppTagsTimeZone	Set the XpoLog's user Time Zone Mode to per AppTags	true/false	Optional

Example of configuring ports:
%JAVA_RUN% %XPLG_CONN% -api settings -httpPort 30304 -sslPort 30444 -ajpPort 8010 -shutdownPort 8096 -agentMode true -activateSecurity true
Example of changing system time zone mode:
%JAVA_RUN% %XPLG_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% %XPLG_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% %XPLG_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% %XPLG_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
description	The description of the account	Test	Optional
hostName	Host Name	Text	Mandatory for new
conType	The connection type (Default: SFTP)	SFTP/SCP	Optional
port	The port to be used in the account (Default: 22)	Number	Optional
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% %XPLG_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 XPLG Account Parameters

Key	Description	Values
api	The API type to use – must be addRemoteXpoLogAccount	“addRemoteXpoLogAccount”	Mandatory
name	The name of the account	Text	Mandatory
description	The description of the account	Test	Optional
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 XPLG account:
%JAVA_RUN% %XPLG_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
description	The description of the account	Text	Optional
externalMediaType	The type of the account	s3	Mandatory (lowercase only)
ema_custom_accessKey	The AWS S3 access key	Text	Mandatory
ema_custom_secretKey	The AWS S3 secret key	Text	Mandatory
override	Override an existing account (Default: false)	true/false	Optional
enabled	Enable/Disable the account	true/false	Optional

Example for adding an S3 account:
%JAVA_RUN% %XPLG_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% %XPLG_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 XPLG 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% %XPLG_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 XPLG 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% %XPLG_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 XPLG 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% %XPLG_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
logName	The name of the log to be created	Text	Mandatory
logPath	The 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 folders	Optional
newLogPath	The new Folders and Logs path to place the log in XPLG Folders and Logs tree (for example Root->Folder1->Folder2).	ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between folders	Optional* If used, override must be true If used, newLogName must not be used
newLogName	The new log name	Text	Optional* 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 - absolute path to the files on the source (name pattern may be used) Remote XPLG Log - the filesPath parameter should be the path of the log under the Folders and Logs tree in the Remote XPLG instance to be added (for example Root->Folder1->Folder2->log1).	Text	Mandatory
collectionPolicy	The exact name of the collection policy to be assigned on the log (if doesn't exist, the command will be ignored)	Text	Optional
accountName	The name of the account to be used if needed (SSH or Win Account or Remote XPLG)	Text	Direct Access - Optional Win Network/SSH - Mandatory
patterns	A 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
appTags	A comma separated list of appTags that the added log will be tagged to	Text	Optional
overrideAppTags	Specifies whether to add appTags on a log or replace the existing appTags of a log. Used only on edit when override is set to true	true/false	Optional
timezone	The timezone definition of the added log	Text (a value from JAVA time zone list)	Optional
charset	The charset definition of the added log	Text (a value from JAVA charset list)	Optional
template	The name of the template to be used	Text	Optional* specific parameters that are passed override template's settings
dataFilterQuery	The dataFilterQuery to be applied on the specified - see Advanced Log Settings for more information. (pass an empty filter to clear an existing filter)	Text	Optional
override	Overwrite an existing log configuration (Default: false)	true/false	Optional

Example of adding a log:
%JAVA_RUN% %XPLG_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% %XPLG_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% %XPLG_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 XPLG from LOG_EXAMPLE to LOG_EXAMPLE_NEW:
%JAVA_RUN% %XPLG_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 XPLG Folders and Logs tree:
%JAVA_RUN% %XPLG_CONN% -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -newLogPath "ROOT->FOLDER_1->FOLDER_2->FOLDER_3" -override "true"

Add Windows Event Logs*

(Note: its required that your XPLG instance will run on Windows to add Windows Event Logs)

Key	Description	Values
api	The API type to use – must be addLog	“addLog”	Mandatory
logName	The name of the log to be created	Text	Mandatory
logPath	The 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 folders	Optional
newLogPath	The new Folders and Logs path to place the log in XPLG Folders and Logs tree (for example Root->Folder1->Folder2).	ROOT = Top Folder (Folders and Logs) Use ‘->’ in the path between folders	Optional* If used, override must be true If used, newLogName must not be used
newLogName	The new log name	Text	Optional* If used, override must be true If used, newLogPath must not be used
host	The host to collect data from (default: localhost)	Text	Optional
unc	True = use direct access to the .evtx file (faster but requires permissions). False = connect via Windows platform (automatic) If a custom path is used ("filesPath") then this property should not be used.	true/false	Optional
collectionPolicy	The exact name of the collection policy to be assigned on the log (if doesn't exist, the command will be ignored)	Text	Optional
accountName	The name of the account to be used if needed (Windows Authentication Account if not used on XPLG service level)	Text	Optional
appTags	A comma separated list of appTags that the added log will be tagged to	Text	Optional
overrideAppTags	Specifies whether to add appTags on a log or replace the existing appTags of a log. Used only on edit when override is set to true	true/false	Optional
timezone	The timezone definition of the added log	Text (a value from JAVA time zone list)	Optional
override	Overwrite an existing log configuration (Default: false)	true/false	Optional
filesPath	The full path to the evtx files on the source (for example: \\servermae\D$\logs\Application.evtx). Note - if "filesPath" is used its mandatory that "unc" should NOT be used.	Text	Optional

Example of adding the Application Windows Event Log (authentication on service level):
%JAVA_RUN% %XPLG_CONN% -api addLog -logName "Application" -logPath "ROOT->Windows Events->localhost" -winEventFileType "Application" -host HOST_NAME -override true -appTags "Windows Event Logs"
Example of adding the Application Windows Event Log (authentication using Windows Authentication Account):
%JAVA_RUN% %XPLG_CONN% -api addLog -logName "Application" -logPath "ROOT->Windows Events->localhost" -winEventFileType "Application" -accountName ACCOUNT_NAME -host HOST_NAME -override true -appTags "Windows Event Logs"
Example of adding the Application Windows Event Log with direct read of EVTX file (authentication on service level):
%JAVA_RUN% %XPLG_CONN% -api addLog -logName "Application" -logPath "ROOT->Windows Events->localhost" -winEventFileType "Application" -unc true -host HOST_NAME -override true -appTags "Windows Event Logs"
Example of adding the Application Windows Event Log with direct read of EVTX file (authentication using Windows Authentication Account):
%JAVA_RUN% %XPLG_CONN% -api addLog -logName "Application" -logPath "ROOT->Windows Events->localhost" -winEventFileType "Application" -accountName ACCOUNT_NAME -unc true -host HOST_NAME -override true -appTags "Windows Event Logs"
Example of adding the Application Windows Event Log in a custom location (authentication using Windows Authentication Account):
%JAVA_RUN% %XPLG_CONN% -api addLog -logName "Application" -logPath "ROOT->Windows Events->localhost" -winEventFileType "Application" -filesPath "\\servername\c$\Logs\Application.evtx" -accountName ACCOUNT_NAME -host HOST_NAME -override true -appTags "Windows Event Logs"

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% %XPLG_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% %XPLG_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 log:
%JAVA_RUN% %XPLG_CONN% -api removeMember -logPath "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% %XPLG_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 XPLG) (The time zone will be applied only if the general User Time Zone Mode in XPLG is set to 'AppTags')	Text	Mandatory
timeZone	A single time zone from JAVA available time zones (The time zone should be exactly as appears in the time zones list, in case XPLG 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)	Text	Mandatory

Example of applying a time zone on an AppTag:
%JAVA_RUN% %XPLG_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 XPLG :
%JAVA_RUN% %XPLG_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% %XPLG_CONN% -api addPatch -type api -files patch.zip

Comments:

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" ...
General Script Example: download here

Common Use Case:

Important: in all examples above we have used %JAVA_RUN% %XPLG_CONN% which is suitable to Windows environments. For Linux, the SDK script should use $JAVA_RUN $XPLG_CONN
Automatically Add Servers to XPLG:
Automating the process of adding new servers to XPLG, 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
Automatically Remove / Disable Servers in XPLG:
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 XPLG from that server, simply disable the account of that specific server so XPLG 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 XPLG including all data then simply remove the account of that server and the folder which contains all its logs. See Script Example: download here