Stats is a simple way to expose certain state to ns_server. And preferred format is expvar’s like as documented elsewhere.

metakv is a simple way for your service to store certain low-traffic metadata (i.e. settings) in cluster-manager. metakv also allows you to subscribe to settings changes. So it makes it simple way for your service consume ns_server-managed settings. It is good at delivering settings changes to your service (or between services) in asynchronous fashion.

Look at godoc of github.com/couchbase/cbauth/metakv package for more details.

revrpc is secure and simple-to-use facility to expose rpc services to ns_server. Unlike metakv it is well suited for cases when you need some synchronous updates from ns_server (and you can return something back too). Now-defunct "cluster topology changes management protocol" where ns_server needs to ask services to update their topology and wait for results is one example. cbauth itself is another. saslauthd-port is using revrpc too.

As revrpc client you typically only need to create your Service instance and than start it via BabysitService while passing your rpc setup function. That function will receive rpc.Server instance and is expected to publish whatever rpc service you need onto that rpc.Server instance. Instances published in this way are available via simple call to ns_server’s json_rpc_connection module. I.e. revrpc gives you all convenience of net/rpc. See net/rpc and net/rpc/jsonrpc godoc for details.

Thus revrpc calls are convenient to use both for ns_server side and golang side.

Note that as of now there are no users of revrpc outside of cbauth itself, but I do anticipate that this might change. It is certainly going to be our preferred choice in cases we’re given choice.

One arguable downside of revrpc is that it’s harder to invoke it manually because it’s not just plain REST API (which is merely a flip side of security advantage mentioned above). We will provide script to help folks perform arbitrary revrpc calls via ns_server.

Under the hood revrpc works by establishing special connection to ns_server (with authorization and via special http method). And then using "plain socket" jsonrpc from ns_server to your service via that connection. Thus "rev" (from reverse) in it’s name. Even though just single connection is used per single revrpc.Service instance, it can deal with arbitrary number of outstanding, in-flight calls. This is feature of json-rpc spec (i.e. out-of-order replies). And golang’s net/rpc facility is enabling it by simply spawning fresh goroutine for every incoming call (which then "injects" response into rpc.ServerCodec as soon as result is ready).

revrpc is usually initialized by CBAUTH_REVRPC_URL variable (of the form of http://%40:<urlencoded-node’s-password>@127.0.0.1:8091/<your-program’s-name>;).

In order to use it for your service look at revrpc.GetDefaultServiceFromEnv. serviceName argument is "subservice" that you want to expose. "cbauth" subservice is reserved for cbauth itself. So your subservice for e.g. indexer could be "main" or "indexer". Then at ns_server’s side Label argument to json_rpc_connection:perform_call function would be 'indexer-indexer' (service, dash, subservice).

Note that there is currently no way to stop revrpc service that is started. Due to lack of demand for that feature.

cbauth is simple way to get credentials to access cluster services and to authenticate/authorize incoming http requests.

See this package’s godoc as well as ./cmd/multi-bucket-demo and ./cmd/cbauth-demo programs for user API.

cbauth works by receiving cluster-manager’s "creds database" via revrpc facility (described above). revrpc itself is configured via environment variable(s) passed by ns_server. So, unlike in initial implementation, cbauth is not directly configured from environment variables anymore, but is merely one of consumers of revrpc.

It is quite important to internalize that cbauth works only if revrpc is properly configured. When your service is started by ns_server this is usually the case.

Sometimes you want to start your application manually (i.e. for debugging). In which case consider looking at cbauth.InternalRetryDefaultInit function for way to initialize cbauth "manually". But note that in any case cbauth will in still depend on working (and up-to-date) ns_server. Or you might want to set revrpc environment variable manually prior to running your program (see above).