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
Tasks Management
- Add/Edit/Execute Add Logs Directory task
- Add/Edit/Execute LogSync task
Folders and Logs Management
- Add Log
- Remove existing folder/log
System Advanced Properties Modifications
Restart
Apply License
Apply Patch
Requirements
- XpoLog Client Jar (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 |
Example of configuring ports:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api settings -httpPort 30304 -sslPort 30444 -ajpPort 8010 -shutdownPort 8096 -agentMode true -activateSecurity true
Linux:
$JAVA_RUN $XPOLOG_CONN -api settings -httpPort 30304 -sslPort 30444 -ajpPort 8010 -shutdownPort 8096 -agentMode true -activateSecurity 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:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api securityUsers -name testUser -userPassword testPassword -displayName "TEST USER" -override true -userPolicy test -selectedGroupsList testgroup;All
Linux:
$JAVA_RUN $XPOLOG_CONN -api securityUsers -name testUser -userPassword testPassword -displayName "TEST USER" -override true -userPolicy test -selectedGroupsList testgroup;All
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
Restart Parameters
Key | Description | Values |
|
api | The API type to use – must be restart | “restart” | Mandatory |
Example of restarting XpoLog:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api restart
Linux:
$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:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api addPatch -type api -files patch.zip
Linux:
$JAVA_RUN $XPOLOG_CONN -api addPatch -type api -files patch.zip
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:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api removeAccount -name "ACCOUNT_NAME"
Linux:
$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:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api enableAccount -name "ACCOUNT_NAME" -enabled false
Linux:
$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 |
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:
Windows:
%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
Linux:
$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 |
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:
Windows:
%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
Linux:
$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
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:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api executeTask -name "TASK_NAME"
Linux:
$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 | Text | Optional |
Example of executing a scan directory operation:
Windows: executeScanTask -name "sdkpizza6" -parentFolderPath "ROOT->pizza6" -scanPath "/home/xplg/xpologConfig/log/UI1"
%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*"
Linux: :
$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 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:
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api addSyncLogTask -name "New Log Sync Test" -configFilePath C:\dev\syncLogsTest.xml -override true -cron "0/10 * * * * ? *"
Linux:
$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 |
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 |
filesPath | The full path to the files on the source (name pattern may be used) | Text | Mandatory |
accountName | The name of the account to be used if needed (SSH or Win Account) | Text | 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 | Mandatory |
override | Overwrite an existing log configuration (Default: false) | true/false | Optional |
Example for adding a log over SSH using an existing account (for direct access simple remove the -accountName parameter):
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -filesPath "/var/log/messages{string}" -accountName "REMOTE_SOURCE_ACCOUNT" -template "LOG_TEMPLATE_NAME"
Linux:
$JAVA_RUN $XPOLOG_CONN -api addLog -logName "LOG_NAME" -logPath "ROOT->FOLDER_1->FOLDER_2" -filesPath "/var/log/messages{string}" -accountName "REMOTE_SOURCE_ACCOUNT" -template "LOG_TEMPLATE_NAME"
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):
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api removeMember -folderPath "ROOT->FOLDER_1->FOLDER_2->FOLDER_NAME_TO_BE_REMOVED"
Linux:
$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):
Windows:
%JAVA_RUN% %XPOLOG_CONN% -api removeMember -folderPath "ROOT->FOLDER_1->FOLDER_2->LOG_NAME_TO_BE_REMOVED"
Linux:
$JAVA_RUN $XPOLOG_CONN -api removeMember -folderPath "ROOT->FOLDER_1->FOLDER_2->LOG_NAME_TO_BE_REMOVED"
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:
- 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 - Automatically Remove / Disable Servers in XpoLog:
- 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 - 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
- Disable Server but keep data that was already collected