Kaginawa server program.
See kaginawa repository for more details.
Docker image is available at Docker Hub.
Administration users must be authorized by OAuth 2.0 provider.
You can choose Auth0, Google and more as an identity provider.
Required environment variables:
AUTH0_DOMAIN- OAuth 2.0 provider domain name (e.g.xxx.auth0.com)AUTH0_CLIENT_ID- OAuth 2.0 provider client IDAUTH0_CLIENT_SECRET- OAuth 2.0 provider client secretSELF_URL- Self URL using OAuth 2.0 callback process (e.g.http://localhost:8080)
If you use the [Deploy to Heroku] button, they will be set automatically by the add-on except SELF_URL.
Required environment variables:
OAUTH_TYPE- Set togoogleOAUTH_CLIENT_ID- OAuth 2.0 provider client IDOAUTH_CLIENT_SECRET- OAuth 2.0 provider client secretSELF_URL- Self URL using OAuth 2.0 callback process (e.g.http://localhost:8080)
See developer.google.com for more information.
Required environment variables:
OAUTH_TYPE- Set tocustomOAUTH_CLIENT_ID- OAuth 2.0 provider client IDOAUTH_CLIENT_SECRET- OAuth 2.0 provider client secretSELF_URL- Self URL using OAuth 2.0 callback process (e.g.http://localhost:8080)OAUTH_AUTH_URL- OAuth 2.0 authorization URLOAUTH_TOKEN_URL- OAuth 2.0 token URLOAUTH_AUDIENCE- OAuth 2.0 audience stringOAUTH_USERINFO_URL- OpenID Connect user info URL
You can choose MongoDB or DynamoDB as a database.
Required environment variable:
MONGODB_URI: MongoDB endpoint (mongodb://user:pass@host:port/db)
Note that MongoDB Atlas may fail to connect with long database name, so exclude all parameters from the connection string (e.g. mongodb+srv://user:pass@cluster/db).
Kaginawa Server automatically creates following collections when first touch:
keys- All API keysservers- All SSH serversnodes- Newest received reports for each nodelogs- All received reports (*1)sessions- Web UI sessions (*2)
*1) We recommend creating logs collection as a capped collection.
Example mongo shell (set to 256 MB):
db.runCommand({"convertToCapped": "logs", size: 268435456})
*2) Session expiration is configurable with TTL indexes feature. Example mongo shell (set to 6 months):
db.sessions.createIndex({"time": 1}, {expireAfterSeconds: 15552000})
Kaginawa server uses AWS default credentials. See the comment of AWS SDK for Go API Reference for more details.
Required environment variables:
DYNAMO_KEYS- Table of keys (e.g.KaginawaKeys)DYNAMO_SERVERS- Table of servers (e.g.KaginawaServers)DYNAMO_NODES- Table of nodes (e.g.KaginawaNodes)DYNAMO_LOGS- Table of logs (e.g.KaginawaLogs)DYNAMO_SESSIONS= Table of sessions (e.g.KaginawaSessions)DYNAMO_CUSTOM_IDS- Index of custom id (e.g.CustomID-index)DYNAMO_LOGS_TTL_DAYS- (Optional) TTL for the table of logsDYNAMO_SESSIONS_TTL_DAYS- (Optional) TTL for the table of sessionsDYNAMO_ENDPOINT- (Optional) Custom endpoint (i.e. using DynamoDB Local)
Create a table of keys using aws-cli:
aws dynamodb create-table \
--table-name KaginawaKeys \
--attribute-definitions AttributeName=Key,AttributeType=S \
--key-schema AttributeName=Key,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
Create a table of servers using aws-cli:
aws dynamodb create-table \
--table-name KaginawaServers \
--attribute-definitions AttributeName=Host,AttributeType=S \
--key-schema AttributeName=Host,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
Create a table of nodes using aws-cli:
aws dynamodb create-table \
--table-name KaginawaNodes \
--attribute-definitions AttributeName=ID,AttributeType=S \
--key-schema AttributeName=ID,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
Create a table of logs using aws-cli:
aws dynamodb create-table \
--table-name KaginawaLogs \
--attribute-definitions \
AttributeName=ID,AttributeType=S \
AttributeName=ServerTime,AttributeType=N \
--key-schema AttributeName=ID,KeyType=HASH AttributeName=ServerTime,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
aws dynamodb update-time-to-live \
--table-name KaginawaLogs \
--time-to-live-specification \
Enabled=true,AttributeName=TTL
Create a table of sessions using aws-cli:
aws dynamodb create-table \
--table-name KaginawaSessions \
--attribute-definitions AttributeName=ID,AttributeType=S \
--key-schema AttributeName=ID,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
aws dynamodb update-time-to-live \
--table-name KaginawaSessions \
--time-to-live-specification \
Enabled=true,AttributeName=TTL
Create an index of custom ID for a table of nodes using aws-cli:
aws dynamodb update-table \
--table-name KaginawaNodes \
--attribute-definitions AttributeName=CustomID,AttributeType=S \
--global-secondary-index-updates \
"[{\"Create\":{\"IndexName\": \"CustomID-index\",\"KeySchema\":[{\"AttributeName\":\"CustomID\",\"KeyType\":\"HASH\"}], \
\"ProvisionedThroughput\": {\"ReadCapacityUnits\": 1, \"WriteCapacityUnits\": 1},\"Projection\":{\"ProjectionType\":\"ALL\"}}}]"
- Method:
GET - Resource:
/nodes - Query Params:
- (Optional)
custom-id- filter by custom-id - (Optional)
minutes- filter by minutes ago - (Optional)
projection- pattern of projection attributes (all,id,list-viewormeasurement)
- (Optional)
- Headers:
Authorization: token <admin_api_key>Accept: application/json
- Response: List of all
Recordobject (see db.go definition)
Curl example with no query params:
curl -H "Authorization: token admin123" -H "Accept: application/json" -X GET "http://localhost:8080/nodes"
Curl example with custom-id:
curl -H "Authorization: token admin123" -H "Accept: application/json" -X GET "http://localhost:8080/nodes?custom-id=dev1"
NOTE: Custom IDs are expect to unique, but can be duplicated (such as device replacements).
Curl example with custom-id and minutes:
curl -H "Authorization: token admin123" -H "Accept: application/json" -X GET "http://localhost:8080/nodes?custom-id=dev1&minutes=5"
Curl example with minutes and projection:
curl -H "Authorization: token admin123" -H "Accept: application/json" -X GET "http://localhost:8080/nodes?minutes=5&projection=id"
- Method:
GET - Resource:
/nodes/:id - Headers:
Authorization: token <admin_api_key>Accept: application/json
- Response: A
Recordobject (see db.go definition)
Curl example:
curl -H "Authorization: token admin123" -H "Accept: application/json" -X GET "http://localhost:8080/nodes/02:00:17:00:7d:b0"
- Method:
POST - Resource:
/nodes/:id/command - Header:
Authorization: token <admin_api_key>
- Form params:
command- commanduser- ssh user name- (Optional)
key- ssh private key - (Optional)
password- ssh password - (Optional)
timeout- timeout seconds (default: 30)
- Response: Command result (MIME:
text/plain)
Curl example:
curl -H "Authorization: token admin123" -X POST -d user=pi -d password=raspberry -d timeout=10 -d command="ls -alh" "http://localhost:8080/nodes/02:00:17:00:7d:b0/command"
- Method:
GET - Resource:
/nodes/:id/history - Header:
Authorization: token <admin_api_key>
- Form params:
- (Optional)
begin- begin time as UTC unix timestamp (default: 24 hours ago) - (Optional)
end- end time as UTC unix timestamp (default: now) - (Optional)
projection- pattern of projection attributes (all,id,list-viewormeasurement)
- (Optional)
- Response: List of all
Recordobject (see db.go definition)
Curl example:
curl -H "Authorization: token admin123" -H "Accept: application/json" -X GET "http://localhost:8080/nodes/02:00:17:00:7d:b0/history&begin=1581900000&end=1582000000"
Kaginawa Server licensed under the BSD 3-clause license.