Laniakea gRPC API Reference
Welcome to the gRPC API reference documentation for Laniakea.
This site features the API documentation for lanicli (CLI), Python,
and Javascript in order to communicate with a laniakea
instance through gRPC.
The examples to the right assume that the there is a remote laniakea
instance
running and listening for gRPC connections on port 7777.
Two things are needed in order to make a gRPC request to an laniakea
instance:
a TLS/SSL connection and a macaroon used for RPC authentication. The examples
to the right will show how these can be used in order to make a successful,
secure, and authenticated gRPC request.
To request an laniakea
instance for testing and development, please visit our customer
experience website at https://live.sssoc.ca. If you do not
have an account with us, please contact us at info@sssoc.ca and we'll
get you started.
The original *.proto
files from which the gRPC documentation was generated
can be found here:
This is the reference for the gRPC API. Alternatively, there is also a REST API which is documented here.
This documentation was
generated automatically against commit
817b0960553cc36b96c796c154d4e91d3e1c3473
.
Tutorial
Python
This section enumerates what you need to do to write a client that communicates
with laniakea
in Python.
$ virtualenv lani
$ source lani/bin/activate
(lani) $ pip install grpcio grpcio-tools googleapis-common-protos
(lani) $ git clone https://github.com/googleapis/googleapis.git
(lani) $ curl -o fmt.proto -s https://raw.githubusercontent.com/SSSOC-CAN/fmt-api/master/protos/lani.proto
(lani) $ python -m grpc_tools.protoc --proto_path=googleapis:. --python_out=. --grpc_python_out=. lani.proto
import lani_pb2 as lani
import lani_pb2_grpc as lanirpc
import grpc
import os
import codecs
# Due to updated ECDSA generated tls.cert we need to let gprc know that
# we need to use that cipher suite otherwise there will be a handhsake
# error when we communicate with the fmtd rpc server.
os.environ["GRPC_SSL_CIPHER_SUITES"] = 'HIGH+ECDSA'
# tls.cert and admin.macaroon are provided to you after successfully
# spinning up an `fmtd` instance via our customer experience website
# For more, visit https://live.sssoc.ca or email us at info@sssoc.ca
cert = open(os.path.expanduser('/path/to/tls.cert'), 'rb').read()
creds = grpc.ssl_channel_credentials(cert)
channel = grpc.secure_channel('some.address:7777', creds)
stub = lanirpc.LaniStub(channel)
with open(os.path.expanduser('/path/to/admin.macaroon'), 'rb') as f:
macaroon_bytes = f.read()
macaroon = codecs.encode(macaroon_bytes, 'hex')
# Invoke the admin-test command
response = stub.AdminTest(lani.AdminTestRequest(), metadata=[('macaroon', macaroon)])
print(response.msg)
Setup and Installation
Laniakea uses the gRPC protocol for communication with clients like lanicli. gRPC is based on protocol buffers and as such, you will need to compile the Laniakea proto file in Python before you can use it to communicate with fmtd.
- Create a virtual environment for your project
- Activate the virtual environment
- Install dependencies (googleapis-common-protos is required due to the use of google/api/annotations.proto)
- Clone the google api's repository (required due to the use of google/api/annotations.proto)
- Copy the fmtd lani.proto file (you'll find them in the
protos
dir at https://github.com/SSSOC-CAN/fmt-api/blob/master/protos/lani.proto) or just download it - Compile the proto file
After following these steps, two files lani_pb2.py
and lani_pb2_grpc.py
will be generated.
These files will be imported in your project anytime you use Python gRPC.
Javascript
This section enumerates what you need to do to write a client that communicates
with laniakea
in Javascript.
$ npm init # (or npm init -f if you want to use the default values without prompt)
$ npm install @grpc/grpc-js @grpc/proto-loader --save
$ curl -o lani.proto -s https://raw.githubusercontent.com/SSSOC-CAN/laniakea-api/master/protos/lani.proto
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA'
// tls.cert and admin.macaroon are provided to you after successfully
// spinning up a `laniakea` instance via our customer experience website
// For more, visit https://live.sssoc.ca or email us at info@sssoc.ca
let m = fs.readFileSync('/path/to/admin.macaroon');
let macaroon = m.toString('hex');
// build meta data credentials
let metadata = new grpc.Metadata()
metadata.add('macaroon', macaroon)
let macaroonCreds = grpc.credentials.createFromMetadataGenerator((_args, callback) => {
callback(null, metadata);
});
// build ssl credentials using the tls cert
let laniCert = fs.readFileSync("/path/to/tls.cert");
let sslCreds = grpc.credentials.createSsl(laniCert);
// combine the cert credentials and the macaroon auth credentials
// such that every call is properly encrypted and authenticated
let credentials = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
// Pass the crendentials when creating a channel
let lanirpcDescriptor = grpc.loadPackageDefinition(packageDefinition);
let lanirpc = lanirpcDescriptor.lanirpc;
let client = new lanirpc.Lani('some.address:7777', credentials);
client.testCommand({}, (err, response) => {
if (err) {
console.log('Error: ' + err);
}
console.log('TestCommand:', response);
});
Setup and Installation
First, you'll need to initialize a simple nodejs project. Then you need to install
the Javascript grpc and proto loader library dependencies. You also need to copy the
laniakea
lani.proto
file in your project directory (or at least somewhere reachable
by your Javascript code). The lani.proto
file is located in the protos
directory
of the laniakea-api
repo.
Service Health
Check
Unary RPC
Check will check the health of various API services and plugins
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/health.proto with the grpcio-tools.
>>> import health_pb2 as lanirpc, health_pb2_grpc as healthstub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = healthstub.HealthStub(channel)
>>> request = lanirpc.HealthRequest(
service=<string>,
)
>>> response = stub.Check(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"status": <array HealthUpdate>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'health.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let health = new lanirpc.Health('some.address:7777', creds);
let request = {
service: <string>,
};
health.check(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "status": <array HealthUpdate>,
// }
gRPC Request: lanirpc.HealthRequest
Parameter | Type | Description |
---|---|---|
service | string | the name of the service or plugin for which we want health information. Leave blank or put all to get all health information |
gRPC Response: lanirpc.HealthResponse
Parameter | Type | Description |
---|---|---|
status | array HealthUpdate | the current states of all given services/plugins |
Service Lani
AdminTest
Unary RPC
AdminTest will send a string response if the proper macaroon is provided.
# A test command which returns a string only if the admin macaroon is provided.
$ lanicli admin-test [arguments...]
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.AdminTestRequest()
>>> response = stub.AdminTest(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"msg": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.adminTest(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "msg": <string>,
// }
gRPC Request: lanirpc.AdminTestRequest
This request has no parameters.
gRPC Response: lanirpc.AdminTestResponse
Parameter | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
BakeMacaroon
Unary RPC
BakeMacaroon will bake a new macaroon based on input permissions and constraints.
# This command bakes a new macaroon based on the provided permissions and optional constraints. Permissions must be of the following format: entity:action
# For specific commands, the format is uri:<command_uri> example: laniakea:write, uri:/lanirpc.Lani/Test this would generate a macaroon with write permissions for any commands associated to the laniakea entity as well as the lanirpc.Lani.Test command
$ lanicli bake-macaroon [command options] permissions
# --timeout_unit value If set, then the the timeout given will be in the specified units. Possible units are:
# - day
# - hour
# - minute
# - second
# second is the default.
# --timeout value If set, the macaroon will timeout after the given number of units. The default unit is seconds. The default timeout is 24 hours (default: 0)
# --save_to value If set, the macaroon will be saved as a .macaroon file at the specified path. The hex encoded macaroon is printed to the console by default
# --plugins value If set, the macaroon will be locked to specified plugins. Enter plugin names, spaced with a colon (e.g. plugin-1:plugin_TWO:PlUgIn-_3Thousand)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.BakeMacaroonRequest(
timeout=<int64>,
timeout_type=<TimeoutType>,
permissions=<array MacaroonPermission>,
plugins=<array string>,
)
>>> response = stub.BakeMacaroon(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"macaroon": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {
timeout: <int64>,
timeout_type: <TimeoutType>,
permissions: <array MacaroonPermission>,
plugins: <array string>,
};
lani.bakeMacaroon(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "macaroon": <string>,
// }
gRPC Request: lanirpc.BakeMacaroonRequest
Parameter | Type | Description |
---|---|---|
timeout | int64 | The length of time for which this macaroon is valid |
timeout_type | TimeoutType | The unit for the macaroon timeout. Choose from SECOND , MINUTE , HOUR or DAY |
permissions | array MacaroonPermission | The list of permissions the new macaroon should grant |
plugins | array string | The list of plugin names to be included in the macaroon |
gRPC Response: lanirpc.BakeMacaroonResponse
Parameter | Type | Description |
---|---|---|
macaroon | string | The hex-encoded macaroon, serialized in binary format |
InsertROIMarker
Unary RPC
Deprecated! InsertROIMarker will no longer be supported
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.InsertROIMarker(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.insertROIMarker(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
LoadTestPlan
Unary RPC
Deprecated! LoadTestPlan will no longer be supported
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.LoadTestPlan(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.loadTestPlan(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
SetPressure
Unary RPC
Deprecated! SetPressure will now be a demo controller plugin which uses PluginAPI Command
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.SetPressure(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.setPressure(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
SetTemperature
Unary RPC
Deprecated! SetTemperature will now be a demo controller plugin which uses PluginAPI Command
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.SetTemperature(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.setTemperature(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
StartRecording
Unary RPC
Deprecated! StartRecording is now /lanirpc.PluginAPI/StartRecord
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.StartRecording(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.startRecording(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
StartTestPlan
Unary RPC
Deprecated! StartTestPlan will no longer be supported
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.StartTestPlan(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.startTestPlan(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
StopDaemon
Unary RPC
StopDaemon will send a shutdown request to the interrupt handler, triggering a graceful shutdown of the daemon.
# Gracefully stop all daemon subprocesses before stopping the daemon itself. This is equivalent to stopping it using CTRL-C.
$ lanicli stop [arguments...]
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.StopRequest()
>>> response = stub.StopDaemon(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.stopDaemon(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.StopRequest
This request has no parameters.
gRPC Response: lanirpc.StopResponse
This response has no parameters.
StopRecording
Unary RPC
Deprecated! StopRecording is now /lanirpc.PluginAPI/StopRecord
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.StopRecording(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.stopRecording(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
StopTestPlan
Unary RPC
Deprecated! StopTestPlan will no longer be supported
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.StopTestPlan(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.stopTestPlan(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
SubscribeDataStream
Unary RPC
Deprecated! SubscribeDataStream is now /lanirpc.PluginAPI/Subscribe
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.SubscribeDataStream(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.subscribeDataStream(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: proto.Empty
This response has no parameters.
TestCommand
Unary RPC
TestCommand will send a string response regardless if a macaroon is provided or not.
# A test command which returns a string for any macaroon provided.
$ lanicli test [arguments...]
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/lani.proto with the grpcio-tools.
>>> import lani_pb2 as lanirpc, lani_pb2_grpc as lanistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = lanistub.LaniStub(channel)
>>> request = lanirpc.TestRequest()
>>> response = stub.TestCommand(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"msg": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lani.proto', loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let lani = new lanirpc.Lani('some.address:7777', creds);
let request = {};
lani.testCommand(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "msg": <string>,
// }
gRPC Request: lanirpc.TestRequest
This request has no parameters.
gRPC Response: lanirpc.TestResponse
Parameter | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
Service PluginAPI
AddPlugin
Unary RPC
AddPlugin will add a plugin from given information.
# Registers and starts a new plugin. The plugin executable must exist in the plugin directory.
$ lanicli plugin-add [command options] plugin-name
# --type value Required. Choose from either datasource or controller.
# --exec value Required. The file name of the plugin executable
# --timeout value The time, in seconds, for an unresponsive plugin to be considered timed out. Default is 30 seconds. (default: 0)
# --maxtimeouts value The number of times a plugin can timeout before being killed. Default is 3. (default: 0)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginConfig(
name=<string>,
type=<string>,
exec_name=<string>,
timeout=<int64>,
max_timeouts=<int64>,
)
>>> response = stub.AddPlugin(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"name": <string>,
"type": <PluginType>,
"state": <PluginState>,
"started_at": <int64>,
"stopped_at": <int64>,
"version": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
type: <string>,
exec_name: <string>,
timeout: <int64>,
max_timeouts: <int64>,
};
pluginAPI.addPlugin(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "name": <string>,
// "type": <PluginType>,
// "state": <PluginState>,
// "started_at": <int64>,
// "stopped_at": <int64>,
// "version": <string>,
// }
gRPC Request: lanirpc.PluginConfig
Parameter | Type | Description |
---|---|---|
name | string | the name of the plugin |
type | string | the type of the plugin, either datasource or controller |
exec_name | string | the name of the executable of the plugin |
timeout | int64 | the time in seconds to determine if a plugin has timed out |
max_timeouts | int64 | the maximum number of times a plugin can timeout |
gRPC Response: lanirpc.Plugin
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin |
type | PluginType | The plugin type (either Datasource or Controller) |
state | PluginState | the current state of the plugin |
started_at | int64 | Unix milli timestamp of when the plugin was started |
stopped_at | int64 | Unix milli timestamp of when the plugin was stopped or killed. Value is 0 if it's not stopped or killed |
version | string | The version number of the plugin, specified in the plugin |
Command
Server-streaming RPC
Command will send any command to a controller service.
# Sends a given controller plugin a command. The command is converted into bytes.
$ lanicli plugin-command [command options] plugin-name
# --command value Required. The actual command being sent to the plugin. The command is then converted to bytes
# --frametype value The type of data being passed to the plugin. Types are usually MIME like strings (e.g. application/json). Default is application/string
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.ControllerPluginRequest(
name=<string>,
frame=<Frame>,
)
>>> for response in stub.Command(request, metadata=[('macaroon', macaroon)]):
print(response)
{
"source": <string>,
"type": <string>,
"timestamp": <int64>,
"payload": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
frame: <Frame>,
};
let call = pluginAPI.command(request);
call.on('data', function(response) {
// A response was received from the server.
console.log(response);
});
call.on('status', function(status) {
// The current status of the stream.
});
call.on('end', function() {
// The server has closed the stream.
});
// Console output:
// {
// "source": <string>,
// "type": <string>,
// "timestamp": <int64>,
// "payload": <bytes>,
// }
gRPC Request: lanirpc.ControllerPluginRequest
Parameter | Type | Description |
---|---|---|
name | string | the name of the plugin we wish to send the command to |
frame | Frame | the data we are sending to the plugin |
gRPC Response: proto.Frame (Streaming)
Parameter | Type | Description |
---|---|---|
source | string | The name of the source of this Frame |
type | string | A MIME-like type indicating the kind of content within the payload field |
timestamp | int64 | The UNIX millisecond timestamp of this frame |
payload | bytes | The actual payload data in bytes. Limit is 2^32 |
GetPlugin
Unary RPC
GetPlugin will retrieve the information for the given plugin.
# Returns the info of a given plugin which includes plugin state, type, start time, stop time, version number, etc.
$ lanicli plugin-info plugin-name
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginRequest(
name=<string>,
)
>>> response = stub.GetPlugin(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"name": <string>,
"type": <PluginType>,
"state": <PluginState>,
"started_at": <int64>,
"stopped_at": <int64>,
"version": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
};
pluginAPI.getPlugin(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "name": <string>,
// "type": <PluginType>,
// "state": <PluginState>,
// "started_at": <int64>,
// "stopped_at": <int64>,
// "version": <string>,
// }
gRPC Request: lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
gRPC Response: lanirpc.Plugin
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin |
type | PluginType | The plugin type (either Datasource or Controller) |
state | PluginState | the current state of the plugin |
started_at | int64 | Unix milli timestamp of when the plugin was started |
stopped_at | int64 | Unix milli timestamp of when the plugin was stopped or killed. Value is 0 if it's not stopped or killed |
version | string | The version number of the plugin, specified in the plugin |
ListPlugins
Unary RPC
ListPlugins will send a list of registered and running plugins.
# Returns a list of all registered plugin which includes plugin state, type, start time, stop time, version number, etc.
$ lanicli plugin-list [arguments...]
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.Empty()
>>> response = stub.ListPlugins(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"plugins": <array Plugin>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {};
pluginAPI.listPlugins(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "plugins": <array Plugin>,
// }
gRPC Request: proto.Empty
This request has no parameters.
gRPC Response: lanirpc.PluginsList
Parameter | Type | Description |
---|---|---|
plugins | array Plugin | List of all currently registered plugins |
StartPlugin
Unary RPC
StartPlugin will start the specified existing plugin. Plugins added in this way will not be present upon laniakea restart
# Start a given plugin. The plugin must be registered to start it.
$ lanicli plugin-start plugin-name
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginRequest(
name=<string>,
)
>>> response = stub.StartPlugin(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
};
pluginAPI.startPlugin(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
gRPC Response: proto.Empty
This response has no parameters.
StartRecord
Unary RPC
StartRecording will begin recording data from specified datasource.
# Start the recording process of a given datasource plugin
$ lanicli plugin-startrecord plugin-name
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginRequest(
name=<string>,
)
>>> response = stub.StartRecord(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
};
pluginAPI.startRecord(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
gRPC Response: proto.Empty
This response has no parameters.
StopPlugin
Unary RPC
StopPlugin will stop the specified plugin.
# Stop a given plugin. The plugin will stop regardless of errors when safely stopping.
$ lanicli plugin-stop plugin-name
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginRequest(
name=<string>,
)
>>> response = stub.StopPlugin(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
};
pluginAPI.stopPlugin(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
gRPC Response: proto.Empty
This response has no parameters.
StopRecord
Unary RPC
StopRecording will end the recording of data from specified datasource.
# Stop the recording process of a given datasource plugin
$ lanicli plugin-stoprecord plugin-name
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginRequest(
name=<string>,
)
>>> response = stub.StopRecord(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
};
pluginAPI.stopRecord(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
gRPC Response: proto.Empty
This response has no parameters.
Subscribe
Server-streaming RPC
Subscribe returns a uni-directional stream of data from a specified datasource.
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginRequest(
name=<string>,
)
>>> for response in stub.Subscribe(request, metadata=[('macaroon', macaroon)]):
print(response)
{
"source": <string>,
"type": <string>,
"timestamp": <int64>,
"payload": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
};
let call = pluginAPI.subscribe(request);
call.on('data', function(response) {
// A response was received from the server.
console.log(response);
});
call.on('status', function(status) {
// The current status of the stream.
});
call.on('end', function() {
// The server has closed the stream.
});
// Console output:
// {
// "source": <string>,
// "type": <string>,
// "timestamp": <int64>,
// "payload": <bytes>,
// }
gRPC Request: lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
gRPC Response: proto.Frame (Streaming)
Parameter | Type | Description |
---|---|---|
source | string | The name of the source of this Frame |
type | string | A MIME-like type indicating the kind of content within the payload field |
timestamp | int64 | The UNIX millisecond timestamp of this frame |
payload | bytes | The actual payload data in bytes. Limit is 2^32 |
SubscribePluginState
Server-streaming RPC
SubscribePluginState will create a stream which pushes plugin state updates to client
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/pluginapi.proto with the grpcio-tools.
>>> import pluginapi_pb2 as lanirpc, pluginapi_pb2_grpc as pluginapistub
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = pluginapistub.PluginAPIStub(channel)
>>> request = lanirpc.PluginRequest(
name=<string>,
)
>>> for response in stub.SubscribePluginState(request, metadata=[('macaroon', macaroon)]):
print(response)
{
"name": <string>,
"state": <PluginState>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'pluginapi.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let pluginAPI = new lanirpc.PluginAPI('some.address:7777', creds);
let request = {
name: <string>,
};
let call = pluginAPI.subscribePluginState(request);
call.on('data', function(response) {
// A response was received from the server.
console.log(response);
});
call.on('status', function(status) {
// The current status of the stream.
});
call.on('end', function() {
// The server has closed the stream.
});
// Console output:
// {
// "name": <string>,
// "state": <PluginState>,
// }
gRPC Request: lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
gRPC Response: lanirpc.PluginStateUpdate (Streaming)
Parameter | Type | Description |
---|---|---|
name | string | the name of the plugin |
state | PluginState | the current state of the plugin |
Service Unlocker
ChangePassword
Unary RPC
ChangePassword prompts the user to enter the current password and enter a new password.
# Changes the previously set password used to unlock the macaroon key-store.
# There are two required arguments for this command, the old password and the new password.
$ lanicli changepassword [command options] [arguments...]
# --new_mac_root_key rotate the macaroon root key resulting in all previously created macaroons to be invalidated
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/unlocker.proto with the grpcio-tools.
>>> import unlocker_pb2 as lanirpc, unlocker_pb2_grpc as unlockerstub
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = unlockerstub.UnlockerStub(channel)
>>> request = lanirpc.ChangePwdRequest(
current_password=<bytes>,
new_password=<bytes>,
new_macaroon_root_key=<bool>,
)
>>> response = stub.ChangePassword(request)
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'unlocker.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const unlocker = new lanirpc.Unlocker('some.address:7777', sslCreds);
let request = {
current_password: <bytes>,
new_password: <bytes>,
new_macaroon_root_key: <bool>,
};
unlocker.changePassword(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.ChangePwdRequest
Parameter | Type | Description |
---|---|---|
current_password | bytes | current_password should be the current valid password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_password | bytes | new_password should be the desired, new password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_macaroon_root_key | bool | new_macaroon_root_key is an optional argument instructing the daemon to rotate the macaroon root key when set to true. This will invalidate all previously generated macaroons. |
gRPC Response: lanirpc.ChangePwdResponse
This response has no parameters.
Login
Unary RPC
Login will prompt the user to provide a password and send the response to the unlocker service for authentication.
# When invoked, user will be prompted to enter a password. Either create one or use an existing one.
$ lanicli login [arguments...]
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/unlocker.proto with the grpcio-tools.
>>> import unlocker_pb2 as lanirpc, unlocker_pb2_grpc as unlockerstub
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = unlockerstub.UnlockerStub(channel)
>>> request = lanirpc.LoginRequest(
password=<bytes>,
)
>>> response = stub.Login(request)
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'unlocker.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const unlocker = new lanirpc.Unlocker('some.address:7777', sslCreds);
let request = {
password: <bytes>,
};
unlocker.login(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.LoginRequest
Parameter | Type | Description |
---|---|---|
password | bytes | The password should be the current valid password for the daemon. This will be required to decrypt on-disk material that the daemon requires to function properly. When using REST, this field must be encoded as base64. |
gRPC Response: lanirpc.LoginResponse
This response has no parameters.
SetPassword
Unary RPC
SetPassword prompts the user to set a password on first startup if no password has already been set.
# Sets a password used to unlock the macaroon key-store when starting weirwood for the first time.
# There is one required argument for this command, the password.
$ lanicli setpassword [arguments...]
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the lanirpc/unlocker.proto with the grpcio-tools.
>>> import unlocker_pb2 as lanirpc, unlocker_pb2_grpc as unlockerstub
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('/path/to/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('some.address:7777', ssl_creds)
>>> stub = unlockerstub.UnlockerStub(channel)
>>> request = lanirpc.SetPwdRequest(
password=<bytes>,
)
>>> response = stub.SetPassword(request)
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync(['lani.proto', 'unlocker.proto'], loaderOptions);
const lanirpc = grpc.loadPackageDefinition(packageDefinition).lanirpc;
const macaroon = fs.readFileSync("/path/to/admin.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('/path/to/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
const unlocker = new lanirpc.Unlocker('some.address:7777', sslCreds);
let request = {
password: <bytes>,
};
unlocker.setPassword(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
gRPC Request: lanirpc.SetPwdRequest
Parameter | Type | Description |
---|---|---|
password | bytes | The password is the password that should be used to encrypt on-disk material that the daemon requires to function properly. After creation, this password is required to unlock the daemon. When using REST, this field must be encoded as base64. |
gRPC Response: lanirpc.SetPwdResponse
This response has no parameters.
gRPC Messages
lanirpc.ControllerPluginRequest
Parameter | Type | Description |
---|---|---|
name | string | the name of the plugin we wish to send the command to |
frame | Frame | the data we are sending to the plugin |
lanirpc.Plugin
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin |
type | PluginType | The plugin type (either Datasource or Controller) |
state | PluginState | the current state of the plugin |
started_at | int64 | Unix milli timestamp of when the plugin was started |
stopped_at | int64 | Unix milli timestamp of when the plugin was stopped or killed. Value is 0 if it's not stopped or killed |
version | string | The version number of the plugin, specified in the plugin |
lanirpc.PluginConfig
Parameter | Type | Description |
---|---|---|
name | string | the name of the plugin |
type | string | the type of the plugin, either datasource or controller |
exec_name | string | the name of the executable of the plugin |
timeout | int64 | the time in seconds to determine if a plugin has timed out |
max_timeouts | int64 | the maximum number of times a plugin can timeout |
lanirpc.PluginRequest
Parameter | Type | Description |
---|---|---|
name | string | The name of the plugin we want to interact with |
lanirpc.PluginStateUpdate
Parameter | Type | Description |
---|---|---|
name | string | the name of the plugin |
state | PluginState | the current state of the plugin |
lanirpc.PluginsList
Parameter | Type | Description |
---|---|---|
plugins | array Plugin | List of all currently registered plugins |
lanirpc.HealthRequest
Parameter | Type | Description |
---|---|---|
service | string | the name of the service or plugin for which we want health information. Leave blank or put all to get all health information |
lanirpc.HealthResponse
Parameter | Type | Description |
---|---|---|
status | array HealthUpdate | the current states of all given services/plugins |
lanirpc.HealthUpdate
Parameter | Type | Description |
---|---|---|
name | string | the name of the service |
state | HealthState | the current state of the service |
proto.Empty
This message has no parameters.
proto.Frame
Parameter | Type | Description |
---|---|---|
source | string | The name of the source of this Frame |
type | string | A MIME-like type indicating the kind of content within the payload field |
timestamp | int64 | The UNIX millisecond timestamp of this frame |
payload | bytes | The actual payload data in bytes. Limit is 2^32 |
proto.VersionNumber
Parameter | Type | Description |
---|---|---|
version | string | version number string |
lanirpc.AdminTestRequest
This message has no parameters.
lanirpc.AdminTestResponse
Parameter | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
lanirpc.BakeMacaroonRequest
Parameter | Type | Description |
---|---|---|
timeout | int64 | The length of time for which this macaroon is valid |
timeout_type | TimeoutType | The unit for the macaroon timeout. Choose from SECOND , MINUTE , HOUR or DAY |
permissions | array MacaroonPermission | The list of permissions the new macaroon should grant |
plugins | array string | The list of plugin names to be included in the macaroon |
lanirpc.BakeMacaroonResponse
Parameter | Type | Description |
---|---|---|
macaroon | string | The hex-encoded macaroon, serialized in binary format |
lanirpc.MacaroonPermission
Parameter | Type | Description |
---|---|---|
entity | string | The entity a permission grants access to |
action | string | The action that is granted |
lanirpc.StopRequest
This message has no parameters.
lanirpc.StopResponse
This message has no parameters.
lanirpc.TestRequest
This message has no parameters.
lanirpc.TestResponse
Parameter | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
lanirpc.ChangePwdRequest
Parameter | Type | Description |
---|---|---|
current_password | bytes | current_password should be the current valid password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_password | bytes | new_password should be the desired, new password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_macaroon_root_key | bool | new_macaroon_root_key is an optional argument instructing the daemon to rotate the macaroon root key when set to true. This will invalidate all previously generated macaroons. |
lanirpc.ChangePwdResponse
This message has no parameters.
lanirpc.LoginRequest
Parameter | Type | Description |
---|---|---|
password | bytes | The password should be the current valid password for the daemon. This will be required to decrypt on-disk material that the daemon requires to function properly. When using REST, this field must be encoded as base64. |
lanirpc.LoginResponse
This message has no parameters.
lanirpc.SetPwdRequest
Parameter | Type | Description |
---|---|---|
password | bytes | The password is the password that should be used to encrypt on-disk material that the daemon requires to function properly. After creation, this password is required to unlock the daemon. When using REST, this field must be encoded as base64. |
lanirpc.SetPwdResponse
This message has no parameters.
gRPC Enums
PluginType
Name | Value | Description |
---|---|---|
DATASOURCE | 0 | |
CONTROLLER | 1 |
PluginState
Name | Value | Description |
---|---|---|
READY | 0 | |
BUSY | 1 | |
STOPPING | 2 | |
STOPPED | 3 | |
UNKNOWN | 4 | |
UNRESPONSIVE | 5 | |
KILLED | 6 |
HealthState
Name | Value | Description |
---|---|---|
UNKNOWN | 0 | |
SERVING | 1 | |
NOT_SERVING | 2 | |
SERVICE_UNKNOWN | 3 |
TimeoutType
Name | Value | Description |
---|---|---|
SECOND | 0 | |
MINUTE | 1 | |
HOUR | 2 | |
DAY | 3 |
Laniakea REST API Reference
Welcome to the REST API reference documentation for Laniakea.
This site features the API documentation for Python and JavaScript, along with
barebones examples using curl
, for HTTP requests.
The examples to the right assume that the there is a remote laniakea
instance
running and listening for REST connections on port 8080.
Two things are needed in order to make a REST request to a laniakea
instance:
a TLS/SSL connection and a macaroon used for RPC authentication. The examples
to the right will show how these can be used in order to make a successful,
secure, and authenticated HTTP request.
To request an laniakea
instance for testing and development, please visit our customer
experience website at https://live.sssoc.ca. If you do not
have an account with us, please contact us at info@sssoc.ca and we'll
get you started.
The original *.swagger.js
files from which the REST documentation was generated
can be found here:
NOTE: The byte
field type must be set as the base64 encoded string
representation of a raw byte array.
This is the reference for the REST API. Alternatively, there is also a gRPC API which is documented here.
This documentation was
generated automatically against commit
817b0960553cc36b96c796c154d4e91d3e1c3473
.
Tutorial
WebSockets with laniakea
's REST API
const host = 'some.address:8080'; // The default REST port of laniakea
const macaroon = '0201036c6e6402eb01030a10625e7e60fd00f5a6f9cd53f33fc82a...'; // The hex encoded macaroon to send
const initialRequest = {name: "test-plugin"} // The initial request to send (see API docs for each RPC).
// The protocol is our workaround for sending the macaroon because custom header
// fields aren't allowed to be sent by the browser when opening a WebSocket.
const protocolString = 'Grpc-Metadata-Macaroon+' + macaroon;
// Let's now connect the web socket. Notice that all WebSocket open calls are
// always GET requests. If the RPC expects a call to be POST or DELETE (see API
// docs to find out), the query parameter "method" can be set to overwrite.
const wsUrl = 'wss://' + host + '/v2/plugin/subscribe?method=GET';
let ws = new WebSocket(wsUrl, protocolString);
ws.onopen = function (event) {
// After the WS connection is establishes, fmtd expects the client to send the
// initial message. If an RPC doesn't have any request parameters, an empty
// JSON object has to be sent as a string, for example: ws.send('{}')
ws.send(JSON.stringify(initialRequest));
}
ws.onmessage = function (event) {
// We received a new message.
console.log(event);
// The data we're really interested in is in data and is always a string
// that needs to be parsed as JSON and always contains a "result" field:
console.log("Payload: ");
console.log(JSON.parse(event.data).result);
}
ws.onerror = function (event) {
// An error occurred, let's log it to the console.
console.log(event);
}
This document describes how streaming response REST calls can be used correctly by making use of the WebSocket API.
As an example, we are going to write a simple JavaScript program that subscribes
to laniakea
's Subscribe
RPC.
The WebSocket will be kept open as long as laniakea
runs and the JavaScript program
isn't stopped.
When using WebSockets in a browser, there are certain security limitations of
what header fields are allowed to be sent. Therefore, the macaroon cannot just
be added as a Grpc-Metadata-Macaroon
header field as it would work with normal
REST calls. The browser will just ignore that header field and not send it.
Instead we have added a workaround in laniakea
's WebSocket proxy that allows
sending the macaroon as a WebSocket "protocol".
API Endpoints
/v1/admin/test
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/admin/test
{
"msg": <string>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/admin/test'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
"msg": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/admin/test',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "msg": <string>,
// }
GET /v1/admin/test
lanicli: admin-test
AdminTest will send a string response if the proper macaroon is provided.
This request has no parameters.
Response
Field | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
/v1/bake/macaroon
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X POST --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/bake/macaroon \
-d '{ "timeout":<string>,"timeout_type":<lanirpcTimeoutType>,"permissions":<array lanirpcMacaroonPermission>,"plugins":<array string>, }'
{
"macaroon": <string>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/bake/macaroon'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'timeout': <string>,
'timeout_type': <lanirpcTimeoutType>,
'permissions': <array lanirpcMacaroonPermission>,
'plugins': <array string>,
}
>>> r = requests.post(url, headers=headers, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"macaroon": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let requestBody = {
timeout: <string>,
timeout_type: <lanirpcTimeoutType>,
permissions: <array lanirpcMacaroonPermission>,
plugins: <array string>,
}
let options = {
url: 'https://some.address:8080/v1/bake/macaroon',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "macaroon": <string>,
// }
POST /v1/bake/macaroon
lanicli: bake-macaroon
BakeMacaroon will bake a new macaroon based on input permissions and constraints.
Field | Type | Placement | Description |
---|---|---|---|
timeout | string | body | The length of time for which this macaroon is valid |
timeout_type | lanirpcTimeoutType | body | The unit for the macaroon timeout. Choose from SECOND , MINUTE , HOUR or DAY |
permissions | array lanirpcMacaroonPermission | body | The list of permissions the new macaroon should grant |
plugins | array string | body | The list of plugin names to be included in the macaroon |
Response
Field | Type | Description |
---|---|---|
macaroon | string | The hex-encoded macaroon, serialized in binary format |
/v1/insert/roi
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/insert/roi
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/insert/roi'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/insert/roi',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/insert/roi
Deprecated! InsertROIMarker will no longer be supported
This request has no parameters.
Response
This response has no parameters.
/v1/load/testplan
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/load/testplan
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/load/testplan'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/load/testplan',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/load/testplan
Deprecated! LoadTestPlan will no longer be supported
This request has no parameters.
Response
This response has no parameters.
/v1/set/pressure
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/set/pressure
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/set/pressure'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/set/pressure',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/set/pressure
Deprecated! SetPressure will now be a demo controller plugin which uses PluginAPI Command
This request has no parameters.
Response
This response has no parameters.
/v1/set/temperature
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/set/temperature
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/set/temperature'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/set/temperature',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/set/temperature
Deprecated! SetTemperature will now be a demo controller plugin which uses PluginAPI Command
This request has no parameters.
Response
This response has no parameters.
/v1/start/recording
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/start/recording
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/start/recording'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/start/recording',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/start/recording
Deprecated! StartRecording is now /lanirpc.PluginAPI/StartRecord
This request has no parameters.
Response
This response has no parameters.
/v1/start/testplan
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/start/testplan
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/start/testplan'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/start/testplan',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/start/testplan
Deprecated! StartTestPlan will no longer be supported
This request has no parameters.
Response
This response has no parameters.
/v1/stop
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X POST --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/stop \
-d '{ }'
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/stop'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
}
>>> r = requests.post(url, headers=headers, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let requestBody = {
}
let options = {
url: 'https://some.address:8080/v1/stop',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
POST /v1/stop
lanicli: stop
StopDaemon will send a shutdown request to the interrupt handler, triggering a graceful shutdown of the daemon.
This request has no parameters.
Response
This response has no parameters.
/v1/stop/recording
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/stop/recording
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/stop/recording'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/stop/recording',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/stop/recording
Deprecated! StopRecording is now /lanirpc.PluginAPI/StopRecord
This request has no parameters.
Response
This response has no parameters.
/v1/stop/testplan
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/stop/testplan
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/stop/testplan'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/stop/testplan',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/stop/testplan
Deprecated! StopTestPlan will no longer be supported
This request has no parameters.
Response
This response has no parameters.
/v1/subscribe/datastream
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/subscribe/datastream
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/subscribe/datastream'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/subscribe/datastream',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
GET /v1/subscribe/datastream
Deprecated! SubscribeDataStream is now /lanirpc.PluginAPI/Subscribe
This request has no parameters.
Response
This response has no parameters.
/v1/test
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/test
{
"msg": <string>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/test'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
"msg": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v1/test',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "msg": <string>,
// }
GET /v1/test
lanicli: test
TestCommand will send a string response regardless if a macaroon is provided or not.
This request has no parameters.
Response
Field | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
/v2/plugin/add
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X POST --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/add \
-d '{ "name":<string>,"type":<string>,"exec_name":<string>,"timeout":<string>,"max_timeouts":<string>, }'
{
"name": <string>,
"type": <PluginPluginType>,
"state": <lanirpcPluginState>,
"started_at": <string>,
"stopped_at": <string>,
"version": <string>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/add'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'name': <string>,
'type': <string>,
'exec_name': <string>,
'timeout': <string>,
'max_timeouts': <string>,
}
>>> r = requests.post(url, headers=headers, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"name": <string>,
"type": <PluginPluginType>,
"state": <lanirpcPluginState>,
"started_at": <string>,
"stopped_at": <string>,
"version": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let requestBody = {
name: <string>,
type: <string>,
exec_name: <string>,
timeout: <string>,
max_timeouts: <string>,
}
let options = {
url: 'https://some.address:8080/v2/plugin/add',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "name": <string>,
// "type": <PluginPluginType>,
// "state": <lanirpcPluginState>,
// "started_at": <string>,
// "stopped_at": <string>,
// "version": <string>,
// }
POST /v2/plugin/add
lanicli: plugin-add
AddPlugin will add a plugin from given information.
Field | Type | Placement | Description |
---|---|---|---|
name | string | body | the name of the plugin |
type | string | body | the type of the plugin, either datasource or controller |
exec_name | string | body | the name of the executable of the plugin |
timeout | string | body | the time in seconds to determine if a plugin has timed out |
max_timeouts | string | body | the maximum number of times a plugin can timeout |
Response
Field | Type | Description |
---|---|---|
name | string | The name of the plugin |
type | PluginPluginType | The plugin type (either Datasource or Controller) |
state | lanirpcPluginState | the current state of the plugin |
started_at | string | Unix milli timestamp of when the plugin was started |
stopped_at | string | Unix milli timestamp of when the plugin was stopped or killed. Value is 0 if it's not stopped or killed |
version | string | The version number of the plugin, specified in the plugin |
/v2/plugin/command
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X POST --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/command \
-d '{ "name":<string>,"frame":<protoFrame>, }'
{
"source": <string>,
"type": <string>,
"timestamp": <string>,
"payload": <byte>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/command'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'name': <string>,
'frame': <protoFrame>,
}
>>> r = requests.post(url, headers=headers, verify=cert_path, stream=True, data=json.dumps(data))
>>> for raw_response in r.iter_lines():
>>> json_response = json.loads(raw_response)
>>> print(json_response)
{
"source": <string>,
"type": <string>,
"timestamp": <string>,
"payload": <byte>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let requestBody = {
name: <string>,
frame: <protoFrame>,
}
let options = {
url: 'https://some.address:8080/v2/plugin/command',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "source": <string>,
// "type": <string>,
// "timestamp": <string>,
// "payload": <byte>,
// }
// --------------------------
// Example with websockets:
// --------------------------
const WebSocket = require('ws');
const fs = require('fs');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let ws = new WebSocket('wss://some.address:8080/v2/plugin/command?method=POST', {
// Work-around for self-signed certificates.
rejectUnauthorized: false,
headers: {
'Grpc-Metadata-Macaroon': macaroon,
},
});
let requestBody = {
name: <string>,
frame: <protoFrame>,
}
ws.on('open', function() {
ws.send(JSON.stringify(requestBody));
});
ws.on('error', function(err) {
console.log('Error: ' + err);
});
ws.on('message', function(body) {
console.log(body);
});
// Console output (repeated for every message in the stream):
// {
// "source": <string>,
// "type": <string>,
// "timestamp": <string>,
// "payload": <byte>,
// }
POST /v2/plugin/command
lanicli: plugin-command
Command will send any command to a controller service.
Field | Type | Placement | Description |
---|---|---|---|
name | string | body | the name of the plugin we wish to send the command to |
frame | protoFrame | body | the data we are sending to the plugin |
Response (streaming)
Field | Type | Description |
---|---|---|
source | string | The name of the source of this Frame |
type | string | A MIME-like type indicating the kind of content within the payload field |
timestamp | string | The UNIX millisecond timestamp of this frame |
payload | byte | The actual payload data in bytes. Limit is 2^32 |
/v2/plugin/start/record
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X PUT --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/start/record/{name}
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/start/record/{name}'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.put(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/plugin/start/record/{name}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.put(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
PUT /v2/plugin/start/record/{name}
lanicli: plugin-startrecord
StartRecording will begin recording data from specified datasource.
Field | Type | Placement | Description |
---|---|---|---|
name | string | path | The name of the plugin we want to interact with |
Response
This response has no parameters.
/v2/plugin/start
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X PUT --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/start/{name}
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/start/{name}'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.put(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/plugin/start/{name}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.put(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
PUT /v2/plugin/start/{name}
lanicli: plugin-start
StartPlugin will start the specified existing plugin. Plugins added in this way will not be present upon laniakea restart
Field | Type | Placement | Description |
---|---|---|---|
name | string | path | The name of the plugin we want to interact with |
Response
This response has no parameters.
/v2/plugin/stop/record
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X PUT --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/stop/record/{name}
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/stop/record/{name}'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.put(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/plugin/stop/record/{name}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.put(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
PUT /v2/plugin/stop/record/{name}
lanicli: plugin-stoprecord
StopRecording will end the recording of data from specified datasource.
Field | Type | Placement | Description |
---|---|---|---|
name | string | path | The name of the plugin we want to interact with |
Response
This response has no parameters.
/v2/plugin/stop
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X PUT --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/stop/{name}
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/stop/{name}'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.put(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/plugin/stop/{name}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.put(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
PUT /v2/plugin/stop/{name}
lanicli: plugin-stop
StopPlugin will stop the specified plugin.
Field | Type | Placement | Description |
---|---|---|---|
name | string | path | The name of the plugin we want to interact with |
Response
This response has no parameters.
/v2/plugin/subscribe
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/subscribe/{name}
{
"source": <string>,
"type": <string>,
"timestamp": <string>,
"payload": <byte>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/subscribe/{name}'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path, stream=True)
>>> for raw_response in r.iter_lines():
>>> json_response = json.loads(raw_response)
>>> print(json_response)
{
"source": <string>,
"type": <string>,
"timestamp": <string>,
"payload": <byte>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/plugin/subscribe/{name}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "source": <string>,
// "type": <string>,
// "timestamp": <string>,
// "payload": <byte>,
// }
// --------------------------
// Example with websockets:
// --------------------------
const WebSocket = require('ws');
const fs = require('fs');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let ws = new WebSocket('wss://some.address:8080/v2/plugin/subscribe/{name}?method=GET', {
// Work-around for self-signed certificates.
rejectUnauthorized: false,
headers: {
'Grpc-Metadata-Macaroon': macaroon,
},
});
let requestBody = {
name: <string>,
}
ws.on('open', function() {
ws.send(JSON.stringify(requestBody));
});
ws.on('error', function(err) {
console.log('Error: ' + err);
});
ws.on('message', function(body) {
console.log(body);
});
// Console output (repeated for every message in the stream):
// {
// "source": <string>,
// "type": <string>,
// "timestamp": <string>,
// "payload": <byte>,
// }
GET /v2/plugin/subscribe/{name}
Subscribe returns a uni-directional stream of data from a specified datasource.
Field | Type | Placement | Description |
---|---|---|---|
name | string | path | The name of the plugin we want to interact with |
Response (streaming)
Field | Type | Description |
---|---|---|
source | string | The name of the source of this Frame |
type | string | A MIME-like type indicating the kind of content within the payload field |
timestamp | string | The UNIX millisecond timestamp of this frame |
payload | byte | The actual payload data in bytes. Limit is 2^32 |
/v2/plugin
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugin/{name}
{
"name": <string>,
"type": <PluginPluginType>,
"state": <lanirpcPluginState>,
"started_at": <string>,
"stopped_at": <string>,
"version": <string>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugin/{name}'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
"name": <string>,
"type": <PluginPluginType>,
"state": <lanirpcPluginState>,
"started_at": <string>,
"stopped_at": <string>,
"version": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/plugin/{name}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "name": <string>,
// "type": <PluginPluginType>,
// "state": <lanirpcPluginState>,
// "started_at": <string>,
// "stopped_at": <string>,
// "version": <string>,
// }
GET /v2/plugin/{name}
lanicli: plugin-info
GetPlugin will retrieve the information for the given plugin.
Field | Type | Placement | Description |
---|---|---|---|
name | string | path | The name of the plugin we want to interact with |
Response
Field | Type | Description |
---|---|---|
name | string | The name of the plugin |
type | PluginPluginType | The plugin type (either Datasource or Controller) |
state | lanirpcPluginState | the current state of the plugin |
started_at | string | Unix milli timestamp of when the plugin was started |
stopped_at | string | Unix milli timestamp of when the plugin was stopped or killed. Value is 0 if it's not stopped or killed |
version | string | The version number of the plugin, specified in the plugin |
/v2/plugins
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/plugins
{
"plugins": <array lanirpcPlugin>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/plugins'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
"plugins": <array lanirpcPlugin>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/plugins',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "plugins": <array lanirpcPlugin>,
// }
GET /v2/plugins
lanicli: plugin-list
ListPlugins will send a list of registered and running plugins.
This request has no parameters.
Response
Field | Type | Description |
---|---|---|
plugins | array lanirpcPlugin | List of all currently registered plugins |
/v1/changepassword
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X POST --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/changepassword \
-d '{ "current_password":<byte>,"new_password":<byte>,"new_macaroon_root_key":<boolean>, }'
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/changepassword'
>>> cert_path = '/path/to/tls.cert'
>>> data = {
'current_password': base64.b64encode(<byte>).decode(),
'new_password': base64.b64encode(<byte>).decode(),
'new_macaroon_root_key': <boolean>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
let requestBody = {
current_password: <byte>,
new_password: <byte>,
new_macaroon_root_key: <boolean>,
}
let options = {
url: 'https://some.address:8080/v1/changepassword',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
POST /v1/changepassword
lanicli: changepassword
ChangePassword prompts the user to enter the current password and enter a new password.
Field | Type | Placement | Description |
---|---|---|---|
current_password | byte | body | current_password should be the current valid password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_password | byte | body | new_password should be the desired, new password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_macaroon_root_key | boolean | body | new_macaroon_root_key is an optional argument instructing the daemon to rotate the macaroon root key when set to true. This will invalidate all previously generated macaroons. |
Response
This response has no parameters.
/v1/login
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X POST --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/login \
-d '{ "password":<byte>, }'
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/login'
>>> cert_path = '/path/to/tls.cert'
>>> data = {
'password': base64.b64encode(<byte>).decode(),
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
let requestBody = {
password: <byte>,
}
let options = {
url: 'https://some.address:8080/v1/login',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
POST /v1/login
lanicli: login
Login will prompt the user to provide a password and send the response to the unlocker service for authentication.
Field | Type | Placement | Description |
---|---|---|---|
password | byte | body | The password should be the current valid password for the daemon. This will be required to decrypt on-disk material that the daemon requires to function properly. When using REST, this field must be encoded as base64. |
Response
This response has no parameters.
/v1/setpassword
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X POST --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v1/setpassword \
-d '{ "password":<byte>, }'
{
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v1/setpassword'
>>> cert_path = '/path/to/tls.cert'
>>> data = {
'password': base64.b64encode(<byte>).decode(),
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
let requestBody = {
password: <byte>,
}
let options = {
url: 'https://some.address:8080/v1/setpassword',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
POST /v1/setpassword
lanicli: setpassword
SetPassword prompts the user to set a password on first startup if no password has already been set.
Field | Type | Placement | Description |
---|---|---|---|
password | byte | body | The password is the password that should be used to encrypt on-disk material that the daemon requires to function properly. After creation, this password is required to unlock the daemon. When using REST, this field must be encoded as base64. |
Response
This response has no parameters.
/v2/health/check
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /path/to/admin.macaroon)"
$ curl -X GET --cacert /path/to/tls.cert --header "$MACAROON_HEADER" https://some.address:8080/v2/health/check/{service}
{
"status": <array lanirpcHealthUpdate>,
}
>>> import base64, codecs, json, requests
>>> url = 'https://some.address:8080/v2/health/check/{service}'
>>> cert_path = '/path/to/tls.cert'
>>> macaroon = codecs.encode(open('/path/to/admin.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, headers=headers, verify=cert_path)
>>> print(r.json())
{
"status": <array lanirpcHealthUpdate>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('/path/to/admin.macaroon').toString('hex');
let options = {
url: 'https://some.address:8080/v2/health/check/{service}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon,
},
}
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "status": <array lanirpcHealthUpdate>,
// }
GET /v2/health/check/{service}
Check will check the health of various API services and plugins
Field | Type | Placement | Description |
---|---|---|---|
service | string | path | the name of the service or plugin for which we want health information. Leave blank or put all to get all health information |
Response
Field | Type | Description |
---|---|---|
status | array lanirpcHealthUpdate | the current states of all given services/plugins |
REST Messages
lanirpcAdminTestResponse
Field | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
lanirpcBakeMacaroonRequest
Field | Type | Description |
---|---|---|
timeout | string | The length of time for which this macaroon is valid |
timeout_type | lanirpcTimeoutType | The unit for the macaroon timeout. Choose from SECOND , MINUTE , HOUR or DAY |
permissions | array lanirpcMacaroonPermission | The list of permissions the new macaroon should grant |
plugins | array string | The list of plugin names to be included in the macaroon |
lanirpcBakeMacaroonResponse
Field | Type | Description |
---|---|---|
macaroon | string | The hex-encoded macaroon, serialized in binary format |
lanirpcChangePwdRequest
Field | Type | Description |
---|---|---|
current_password | byte | current_password should be the current valid password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_password | byte | new_password should be the desired, new password used to unlock the daemon. When using REST, this field must be encoded as base64. |
new_macaroon_root_key | boolean | new_macaroon_root_key is an optional argument instructing the daemon to rotate the macaroon root key when set to true. This will invalidate all previously generated macaroons. |
lanirpcChangePwdResponse
This property has no parameters.
lanirpcControllerPluginRequest
Field | Type | Description |
---|---|---|
name | string | the name of the plugin we wish to send the command to |
frame | protoFrame | the data we are sending to the plugin |
lanirpcHealthResponse
Field | Type | Description |
---|---|---|
status | array lanirpcHealthUpdate | the current states of all given services/plugins |
lanirpcHealthUpdate
Field | Type | Description |
---|---|---|
name | string | the name of the service |
state | HealthUpdateHealthState | the current state of the service |
lanirpcLoginRequest
Field | Type | Description |
---|---|---|
password | byte | The password should be the current valid password for the daemon. This will be required to decrypt on-disk material that the daemon requires to function properly. When using REST, this field must be encoded as base64. |
lanirpcLoginResponse
This property has no parameters.
lanirpcMacaroonPermission
Field | Type | Description |
---|---|---|
entity | string | The entity a permission grants access to |
action | string | The action that is granted |
lanirpcPlugin
Field | Type | Description |
---|---|---|
name | string | The name of the plugin |
type | PluginPluginType | The plugin type (either Datasource or Controller) |
state | lanirpcPluginState | the current state of the plugin |
started_at | string | Unix milli timestamp of when the plugin was started |
stopped_at | string | Unix milli timestamp of when the plugin was stopped or killed. Value is 0 if it's not stopped or killed |
version | string | The version number of the plugin, specified in the plugin |
lanirpcPluginConfig
Field | Type | Description |
---|---|---|
name | string | the name of the plugin |
type | string | the type of the plugin, either datasource or controller |
exec_name | string | the name of the executable of the plugin |
timeout | string | the time in seconds to determine if a plugin has timed out |
max_timeouts | string | the maximum number of times a plugin can timeout |
lanirpcPluginStateUpdate
Field | Type | Description |
---|---|---|
name | string | the name of the plugin |
state | lanirpcPluginState | the current state of the plugin |
lanirpcPluginsList
Field | Type | Description |
---|---|---|
plugins | array lanirpcPlugin | List of all currently registered plugins |
lanirpcSetPwdRequest
Field | Type | Description |
---|---|---|
password | byte | The password is the password that should be used to encrypt on-disk material that the daemon requires to function properly. After creation, this password is required to unlock the daemon. When using REST, this field must be encoded as base64. |
lanirpcSetPwdResponse
This property has no parameters.
lanirpcStopRequest
This property has no parameters.
lanirpcStopResponse
This property has no parameters.
lanirpcTestResponse
Field | Type | Description |
---|---|---|
msg | string | A short message indicating success or failure |
protoEmpty
This property has no parameters.
protoFrame
Field | Type | Description |
---|---|---|
source | string | The name of the source of this Frame |
type | string | A MIME-like type indicating the kind of content within the payload field |
timestamp | string | The UNIX millisecond timestamp of this frame |
payload | byte | The actual payload data in bytes. Limit is 2^32 |
protobufAny
Field | Type | Description |
---|---|---|
@type | string |
rpcStatus
Field | Type | Description |
---|---|---|
code | int32 | |
message | string | |
details | array protobufAny |
REST Enums
lanirpcTimeoutType
Name | Value | Description |
---|---|---|
SECOND | 0 | |
MINUTE | 1 | |
HOUR | 2 | |
DAY | 3 |
PluginPluginType
Name | Value | Description |
---|---|---|
DATASOURCE | 0 | |
CONTROLLER | 1 |
lanirpcPluginState
Name | Value | Description |
---|---|---|
READY | 0 | |
BUSY | 1 | |
STOPPING | 2 | |
STOPPED | 3 | |
UNKNOWN | 4 | |
UNRESPONSIVE | 5 | |
KILLED | 6 |
HealthUpdateHealthState
Name | Value | Description |
---|---|---|
UNKNOWN | 0 | |
SERVING | 1 | |
NOT_SERVING | 2 | |
SERVICE_UNKNOWN | 3 |
Other API References
This is the gRPC and REST API reference for Laniakea.