bootstrap

README

BOOTSTRAP SERVICE

New devices need to be configured properly and connected to the Mainflux. Bootstrap service is used in order to accomplish that. This service provides the following features:

1. Creating new Mainflux Things
2. Providing basic configuration for the newly created Things
3. Enabling/disabling Things

Pre-provisioning a new Thing is as simple as sending Configuration data to the Bootstrap service. Once the Thing is online, it sends a request for initial config to Bootstrap service. Bootstrap service provides an API for enabling and disabling Things. Only enabled Things can exchange messages over Mainflux. Bootstrapping does not implicitly enable Things, it has to be done manually.

In order to bootstrap successfully, the Thing needs to send bootstrapping request to the specific URL, as well as a secret key. This key and URL are pre-provisioned during the manufacturing process. If the Thing is provisioned on the Bootstrap service side, the corresponding configuration will be sent as a response. Otherwise, the Thing will be saved so that it can be provisioned later.

Thing Configuration Entity

Thing Configuration consists of two logical parts: the custom configuration that can be interpreted by the Thing itself and Mainflux-related configuration. Mainflux config contains:

1. corresponding Mainflux Thing ID
2. corresponding Mainflux Thing key
3. list of the Mainflux channels the Thing is connected to

Note: list of channels contains IDs of the Mainflux channels. These channels are pre-provisioned on the Mainflux side and, unlike corresponding Mainflux Thing, Bootstrap service is not able to create Mainflux Channels.

Enabling and disabling Thing (adding Thing to/from whitelist) is as simple as connecting corresponding Mainflux Thing to the given list of Channels. Configuration keeps state of the Thing:

State	What it means
Inactive	Thing is created, but isn't enabled
Active	Thing is able to communicate using Mainflux

Switching between states Active and Inactive enables and disables Thing, respectively.

Thing configuration also contains the so-called external ID and external key. An external ID is a unique identifier of corresponding Thing. For example, a device MAC address is a good choice for external ID. External key is a secret key that is used for authentication during the bootstrapping procedure.

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Variable	Description	Default
MF_BOOTSTRAP_LOG_LEVEL	Log level for Bootstrap (debug, info, warn, error)	error
MF_BOOTSTRAP_DB_HOST	Database host address	localhost
MF_BOOTSTRAP_DB_PORT	Database host port	5432
MF_BOOTSTRAP_DB_USER	Database user	mainflux
MF_BOOTSTRAP_DB_PASS	Database password	mainflux
MF_BOOTSTRAP_DB	Name of the database used by the service	bootstrap
MF_BOOTSTRAP_DB_SSL_MODE	Database connection SSL mode (disable, require, verify-ca, verify-full)	disable
MF_BOOTSTRAP_DB_SSL_CERT	Path to the PEM encoded certificate file
MF_BOOTSTRAP_DB_SSL_KEY	Path to the PEM encoded key file
MF_BOOTSTRAP_DB_SSL_ROOT_CERT	Path to the PEM encoded root certificate file
MF_BOOTSTRAP_ENCRYPT_KEY	Secret key for secure bootstrapping encryption	12345678910111213141516171819202
MF_BOOTSTRAP_CLIENT_TLS	Flag that indicates if TLS should be turned on	false
MF_BOOTSTRAP_CA_CERTS	Path to trusted CAs in PEM format
MF_BOOTSTRAP_PORT	Bootstrap service HTTP port	8180
MF_BOOTSTRAP_SERVER_CERT	Path to server certificate in pem format
MF_BOOTSTRAP_SERVER_KEY	Path to server key in pem format
MF_SDK_BASE_URL	Base url for Mainflux SDK	http://localhost
MF_SDK_THINGS_PREFIX	SDK prefix for Things service
MF_THINGS_ES_URL	Things service event source URL	localhost:6379
MF_THINGS_ES_PASS	Things service event source password
MF_THINGS_ES_DB	Things service event source database	0
MF_BOOTSTRAP_ES_URL	Bootstrap service event source URL	localhost:6379
MF_BOOTSTRAP_ES_PASS	Bootstrap service event source password
MF_BOOTSTRAP_ES_DB	Bootstrap service event source database	0
MF_BOOTSTRAP_EVENT_CONSUMER	Bootstrap service event source consumer name	bootstrap
MF_JAEGER_URL	Jaeger server URL	localhost:6831
MF_AUTH_GRPC_URL	Auth service gRPC URL	localhost:8181
MF_AUTH_GRPC_TIMEOUT	Auth service gRPC request timeout in seconds	1s

Deployment

The service itself is distributed as Docker container. Check the boostrap service section in docker-compose to see how service is deployed.

To start the service outside of the container, execute the following shell script:

# download the latest version of the service
git clone https://github.com/mainflux/mainflux

cd mainflux

# compile the service
make bootstrap

# copy binary to bin
make install

# set the environment variables and run the service
MF_BOOTSTRAP_LOG_LEVEL=[Bootstrap log level] \
MF_BOOTSTRAP_DB_HOST=[Database host address] \
MF_BOOTSTRAP_DB_PORT=[Database host port] \
MF_BOOTSTRAP_DB_USER=[Database user] \
MF_BOOTSTRAP_DB_PASS=[Database password] \
MF_BOOTSTRAP_DB=[Name of the database used by the service] \
MF_BOOTSTRAP_DB_SSL_MODE=[SSL mode to connect to the database with] \
MF_BOOTSTRAP_DB_SSL_CERT=[Path to the PEM encoded certificate file] \
MF_BOOTSTRAP_DB_SSL_KEY=[Path to the PEM encoded key file] \
MF_BOOTSTRAP_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file] \
MF_BOOTSTRAP_ENCRYPT_KEY=[Hex-encoded encryption key used for secure bootstrap] \
MF_BOOTSTRAP_CLIENT_TLS=[Boolean value to enable/disable client TLS] \
MF_BOOTSTRAP_CA_CERTS=[Path to trusted CAs in PEM format] \
MF_BOOTSTRAP_PORT=[Service HTTP port] \
MF_BOOTSTRAP_SERVER_CERT=[Path to server certificate] \
MF_BOOTSTRAP_SERVER_KEY=[Path to server key] \
MF_SDK_BASE_URL=[Base SDK URL for the Mainflux services] \
MF_SDK_THINGS_PREFIX=[SDK prefix for Things service] \
MF_JAEGER_URL=[Jaeger server URL] \
MF_AUTH_GRPC_URL=[Auth service gRPC URL] \
MF_AUTH_GRPC_TIMEOUT=[Auth service gRPC request timeout in seconds] \
$GOBIN/mainflux-bootstrap

Setting MF_BOOTSTRAP_CA_CERTS expects a file in PEM format of trusted CAs. This will enable TLS against the Users gRPC endpoint trusting only those CAs that are provided.

Usage

For more information about service capabilities and its usage, please check out the API documentation.

Documentation

Overview

Package bootstrap contains the domain concept definitions needed to support Mainflux bootstrap service functionality.

Index

• Variables
• type Channel
• type Config
• type ConfigReader
  • func NewConfigReader(encKey []byte) ConfigReader
• type ConfigRepository
• type ConfigsPage
• type Filter
• type Service
  • func New(auth mainflux.AuthServiceClient, configs ConfigRepository, sdk mfsdk.SDK, ...) Service
• type State
  • func (s State) String() string

Variables

var (
	// ErrThings indicates failure to communicate with Mainflux Things service.
	// It can be due to networking error or invalid/unauthenticated request.
	ErrThings = errors.New("failed to receive response from Things service")

	// ErrExternalKey indicates a non-existent bootstrap configuration for given external key
	ErrExternalKey = errors.New("failed to get bootstrap configuration for given external key")

	// ErrExternalKeySecure indicates error in getting bootstrap configuration for given encrypted external key
	ErrExternalKeySecure = errors.New("failed to get bootstrap configuration for given encrypted external key")

	// ErrBootstrap indicates error in getting bootstrap configuration.
	ErrBootstrap = errors.New("failed to read bootstrap configuration")
)

Types

type Channel

type Channel struct {
	ID       string
	Name     string
	Metadata map[string]interface{}
}

Channel represents Mainflux channel corresponding Mainflux Thing is connected to.

type Config

type Config struct {
	MFThing     string
	Owner       string
	Name        string
	ClientCert  string
	ClientKey   string
	CACert      string
	MFKey       string
	MFChannels  []Channel
	ExternalID  string
	ExternalKey string
	Content     string
	State       State
}

Config represents Configuration entity. It wraps information about external entity as well as info about corresponding Mainflux entities. MFThing represents corresponding Mainflux Thing ID. MFKey is key of corresponding Mainflux Thing. MFChannels is a list of Mainflux Channels corresponding Mainflux Thing connects to.

type ConfigReader

type ConfigReader interface {
	ReadConfig(Config, bool) (interface{}, error)
}

ConfigReader is used to parse Config into format which will be encoded as a JSON and consumed from the client side. The purpose of this interface is to provide convenient way to generate custom configuration response based on the specific Config which will be consumed by the client.

func NewConfigReader

func NewConfigReader(encKey []byte) ConfigReader

NewConfigReader return new reader which is used to generate response from the config.

type ConfigRepository

type ConfigRepository interface {
	// Save persists the Config. Successful operation is indicated by non-nil
	// error response.
	Save(cfg Config, chsConnIDs []string) (string, error)

	// RetrieveByID retrieves the Config having the provided identifier, that is owned
	// by the specified user.
	RetrieveByID(owner, id string) (Config, error)

	// RetrieveAll retrieves a subset of Configs that are owned
	// by the specific user, with given filter parameters.
	RetrieveAll(owner string, filter Filter, offset, limit uint64) ConfigsPage

	// RetrieveByExternalID returns Config for given external ID.
	RetrieveByExternalID(externalID string) (Config, error)

	// Update updates an existing Config. A non-nil error is returned
	// to indicate operation failure.
	Update(cfg Config) error

	// UpdateCerts updates an existing Config certificate and owner.
	// A non-nil error is returned to indicate operation failure.
	UpdateCert(owner, thingID, clientCert, clientKey, caCert string) error

	// UpdateConnections updates a list of Channels the Config is connected to
	// adding new Channels if needed.
	UpdateConnections(owner, id string, channels []Channel, connections []string) error

	// Remove removes the Config having the provided identifier, that is owned
	// by the specified user.
	Remove(owner, id string) error

	// ChangeState changes of the Config, that is owned by the specific user.
	ChangeState(owner, id string, state State) error

	// ListExisting retrieves those channels from the given list that exist in DB.
	ListExisting(owner string, ids []string) ([]Channel, error)

	// RemoveThing removes Config of the Thing with the given ID.
	RemoveThing(id string) error

	// UpdateChannel updates channel with the given ID.
	UpdateChannel(c Channel) error

	// RemoveChannel removes channel with the given ID.
	RemoveChannel(id string) error

	// DisconnectHandler changes state of the Config when the corresponding Thing is
	// disconnected from the Channel.
	DisconnectThing(channelID, thingID string) error
}

ConfigRepository specifies a Config persistence API.

type ConfigsPage

type ConfigsPage struct {
	Total   uint64
	Offset  uint64
	Limit   uint64
	Configs []Config
}

ConfigsPage contains page related metadata as well as list of Configs that belong to this page.

type Filter

type Filter struct {
	FullMatch    map[string]string
	PartialMatch map[string]string
}

Filter is used for the search filters.

type Service

type Service interface {
	// Add adds new Thing Config to the user identified by the provided token.
	Add(ctx context.Context, token string, cfg Config) (Config, error)

	// View returns Thing Config with given ID belonging to the user identified by the given token.
	View(ctx context.Context, token, id string) (Config, error)

	// Update updates editable fields of the provided Config.
	Update(ctx context.Context, token string, cfg Config) error

	// UpdateCert updates an existing Config certificate and token.
	// A non-nil error is returned to indicate operation failure.
	UpdateCert(ctx context.Context, token, thingID, clientCert, clientKey, caCert string) error

	// UpdateConnections updates list of Channels related to given Config.
	UpdateConnections(ctx context.Context, token, id string, connections []string) error

	// List returns subset of Configs with given search params that belong to the
	// user identified by the given token.
	List(ctx context.Context, token string, filter Filter, offset, limit uint64) (ConfigsPage, error)

	// Remove removes Config with specified token that belongs to the user identified by the given token.
	Remove(ctx context.Context, token, id string) error

	// Bootstrap returns Config to the Thing with provided external ID using external key.
	Bootstrap(ctx context.Context, externalKey, externalID string, secure bool) (Config, error)

	// ChangeState changes state of the Thing with given ID and owner.
	ChangeState(ctx context.Context, token, id string, state State) error

	// UpdateChannelHandler updates Channel with data received from an event.
	UpdateChannelHandler(ctx context.Context, channel Channel) error

	// RemoveConfigHandler removes Configuration with id received from an event.
	RemoveConfigHandler(ctx context.Context, id string) error

	// RemoveChannelHandler removes Channel with id received from an event.
	RemoveChannelHandler(ctx context.Context, id string) error

	// DisconnectHandler changes state of the Config when connect/disconnect event occurs.
	DisconnectThingHandler(ctx context.Context, channelID, thingID string) error
}

Service specifies an API that must be fulfilled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

func New

func New(auth mainflux.AuthServiceClient, configs ConfigRepository, sdk mfsdk.SDK, encKey []byte) Service

New returns new Bootstrap service.

type State

type State int

State represents corresponding Mainflux Thing state. The possible Config States as well as description of what that State represents are given in the table: | State | What it means | |----------+--------------------------------------------------------------------------------| | Inactive | Thing is created, but isn't able to communicate over Mainflux | | Active | Thing is able to communicate using Mainflux |

const (
	// Inactive Thing is created, but not able to exchange messages using Mainflux.
	Inactive State = iota
	// Active Thing is created, configured, and whitelisted.
	Active
)

func (State) String

func (s State) String() string

String returns string representation of State.