https://github.com/estuaryoss/estuary-agent-java
Estuary Agent is a Spring Boot service that runs your shell commands via pure REST API. Part of the Estuary stack.
https://github.com/estuaryoss/estuary-agent-java
api-control automation-as-a-service distributed-testing estuary-stack parallel-testing remote-config remote-control remote-shell standardization test-automation test-automation-as-a-service testing testing-tool testing-tools
Last synced: about 1 month ago
JSON representation
Estuary Agent is a Spring Boot service that runs your shell commands via pure REST API. Part of the Estuary stack.
- Host: GitHub
- URL: https://github.com/estuaryoss/estuary-agent-java
- Owner: estuaryoss
- License: apache-2.0
- Archived: true
- Created: 2020-09-12T12:21:18.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-31T15:28:26.000Z (almost 3 years ago)
- Last Synced: 2025-07-24T12:47:40.817Z (7 months ago)
- Topics: api-control, automation-as-a-service, distributed-testing, estuary-stack, parallel-testing, remote-config, remote-control, remote-shell, standardization, test-automation, test-automation-as-a-service, testing, testing-tool, testing-tools
- Language: Java
- Homepage: http://estuaryoss.github.io
- Size: 12 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# About
The agent is written in Java (SpringBoot), and it executes low-level commands.
It enables any use case which implies system commands:
- Controlling and configuring the machines (via REST API)
- Exposing CLI applications via REST API
- Testing support by enabling SUT control and automation framework control
- IoT
- Home control integrations
It supports command execution having several modes:
- Commands executed sequentially
- Commands executed in parallel
- Commands executed in background
- Commands executed synchronously
With the help of the agent the user can also do IO operations:
- File upload and download (binary / text)
- Folder download (as zip archive)
This code acts both as a microservice as well as a library:
a) Standalone microservice jar with the
extension: [exec.jar](https://search.maven.org/artifact/com.github.estuaryoss/agent/4.2.0/jar)
```bash
java -jar agent-4.2.2-exec.jar
```
b) Library as a Maven dependency:
```xml
com.github.estuaryoss
agent
4.2.2
```
## Artifact
## Build status
[](https://circleci.com/gh/estuaryoss/estuary-agent-java)
## Code quality
[](https://www.codacy.com/gh/estuaryoss/estuary-agent-java/dashboard?utm_source=github.com&utm_medium=referral&utm_content=estuaryoss/estuary-agent-java&utm_campaign=Badge_Grade)
[](https://codeclimate.com/repos/5f6783d35aa6290178006578/maintainability)
## Postman collection
The postman collection is saved in folder **docs**
## Commands in background
Send your command using the classic endpoints, and then timeout from client.
Use **/commands**, **/commands/running** and **/commands/finished** GET to retrieve your command information.
## Eureka client registration
Set the following env vars:
- APP_IP -> the ip which this service binds to
- PORT -> the port which this service binds to
Example:
```bash
export APP_IP=192.168.0.4
export PORT=8081
java -jar \
-Deureka.client.serviceUrl.defaultZone=http://192.168.0.100:8080/eureka/v2 \
-Deureka.client.enabled=true agent-4.2.3-SNAPSHOT-exec.jar
```
## Fluentd logging
- FLUENTD_IP_PORT -> This env var sets the fluentd ip:port connection. Example: localhost:24224
## Authentication
### Method 1 - Spring security
- HTTP_AUTH_USER
- HTTP_AUTH_PASSWORD
These env vars will be matched against basic authentication from your HttpClient.
After user auth, set the received cookie (JSESSIONID) to communicate further with the agent.
The same settings can be set through application properties: **app.user** & **app.password**.
The env vars precedence is higher than the one set through the application properties.
[!!!]() Use these env variables or swap application.properties file if you use it as dependency, otherwise you will open
a major security hole. The attacker will have access to your system. [!!!]()
### Method 2 - Token auth - No spring-security
- HTTP_AUTH_TOKEN -> This env var sets the auth token for the service. Will be matched with the header 'Token'
Note: The profile to be used is 'test'.
## Command timeout
- COMMAND_TIMEOUT -> This env var sets the command timeout for the system commands. Default is **1800** seconds.
## Enable HTTPS
Set **HTTPS_ENABLE** env var option to *true* or *false*.
Set the certificate path (is relative!) with **HTTPS_KEYSTORE** and **HTTPS_KEYSTORE_PASSWORD** env variables. E.g.
HTTPS_KEYSTORE=file:https/keystore.p12
If you do not set cert and keystore password env vars, it uses the ones from default *application.properties* in the
resource folder.
! Please also set the following env vars:
- the app port by setting the env var called **PORT** to *8443*. Default is 8080.
- **SERVICE_PROTOCOL** to *https*
## Environment variables injection
User defined environment variables will be stored in a 'virtual' environment. The extra env vars will be used by the
process that executes system commands.
There are two ways to inject user defined environment variables.
- call POST on **/env** endpoint. The body will contain the env vars in JSON format. E.g. {"FOO1":"BAR1"}
- create an **environment.properties** file with the extra env vars needed and place it in the same path as the JAR.
Example in this repo.
*! All environment variables described above can also be set using **environment.properties**. However, the vars set
through **application.yml** can't be set: PORT, APP_IP, EUREKA_SERVER.*
## Example output
curl -X POST -d 'ls -lrt' http://localhost:8080/command
```json
{
"code": 1000,
"message": "Success",
"description": {
"finished": true,
"started": false,
"startedat": "2020-08-15 19:38:16.138962",
"finishedat": "2020-08-15 19:38:16.151067",
"duration": 0.012,
"pid": 2315,
"id": "none",
"commands": {
"ls -lrt": {
"status": "finished",
"details": {
"out": "total 371436\n-rwxr-xr-x 1 dinuta qa 13258464 Jun 24 09:25 main-linux\ndrwxr-xr-x 4 dinuta qa 40 Jul 1 11:42 tmp\n-rw-r--r-- 1 dinuta qa 77707265 Jul 25 19:38 testrunner-linux.zip\n-rw------- 1 dinuta qa 4911271 Aug 14 10:00 nohup.out\n",
"err": "",
"code": 0,
"pid": 6803,
"args": [
"/bin/sh",
"-c",
"ls -lrt"
]
},
"startedat": "2020-08-15 19:38:16.138970",
"finishedat": "2020-08-15 19:38:16.150976",
"duration": 0.012
}
}
},
"timestamp": "2020-08-15 19:38:16.151113",
"path": "/command?",
"name": "estuary-agent",
"version": "4.0.8"
}
```
## Overview
The underlying library integrating swagger to SpringBoot is [springfox](https://github.com/springfox/springfox)
Start your server as an simple java application
You can view the api documentation in swagger-ui by pointing to
http://localhost:8080/
Change default port value in application.properties
## Maven dependency && settings.xml
Get this dependency:
```xml
com.github.estuaryoss
agent
4.0.8
```
## Maven devendency snapshot
```xml
com.github.estuaryoss
agent
4.2.3-SNAPSHOT
```
To use a snapshot version, set the s01.oss.sonatype.org repo in settings.xml:
```xml
snaphosts4
true
false
always
all-external8
https://s01.oss.sonatype.org/content/repositories/snapshots/
```
To generate Query classes needed for the DB queries run:
mvn clean install (-DskipTests=true for faster compilation)
## Resources
- https://springdoc.org/#migrating-from-springfox
- https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
Support
project: 