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:

• health.proto
• lani.proto
• plugin.proto
• pluginapi.proto
• unlocker.proto

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.

1. Create a virtual environment for your project
2. Activate the virtual environment
3. Install dependencies (googleapis-common-protos is required due to the use of google/api/annotations.proto)
4. Clone the google api's repository (required due to the use of google/api/annotations.proto)
5. 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
6. 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:

• lani.swagger.json
• pluginapi.swagger.json
• unlocker.swagger.json
• health.swagger.json

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.