Add documentation to config options for the cli

client/config.go

@@ -89,46 +89,50 @@ const (
 
 // Config sets the HTTP client configuration
 type Config struct {
+	// Log level
+	Log string `desc:"Set log level to info, error or debug"`
+
 	// Endpoints [host:port,host:port,...] to ask for QED cluster-topology.
-	Endpoints []string
+	Endpoints []string `desc:"REST QED Log service endpoint list http://ip1:port1,http://ip2:port2... "`
 
 	// ApiKey to query the server endpoint.
-	APIKey string
+	APIKey string `desc:"Set API Key to talk to QED Log service"`
 
 	// Insecure enables the verification of the server's certificate chain
 	// and host name, allowing MiTM vector attacks.
-	Insecure bool
+	Insecure bool `desc:"Set it to true to disable the verification of the server's certificate chain"`
 
-	// Timeout is the number of seconds to wait for a request to QED.
-	Timeout time.Duration
+	// Timeout is the time to wait for a request to QED.
+	Timeout time.Duration `desc:"Time to wait for a request to QED"`
 
-	// DialTimeout is the number of seconds to wait for the connection to be established.
-	DialTimeout time.Duration
+	// DialTimeout is the time to wait for the connection to be established.
+	DialTimeout time.Duration `desc:"Time to wait for the connection to be established"`
 
-	// HandshakeTimeout is the number of seconds to wait for a handshake negotiation.
-	HandshakeTimeout time.Duration
+	// HandshakeTimeout is the time to wait for a handshake negotiation.
+	HandshakeTimeout time.Duration `desc:"Time to wait for a handshake negotiation"`
 
 	// Controls how the client will route all queries to members of the cluster.
-	ReadPreference ReadPref
+	ReadPreference ReadPref `flag:"-"`
 
 	// MaxRetries sets the maximum number of retries before giving up
 	// when performing an HTTP request to QED.
-	MaxRetries int
+	MaxRetries int `desc:"Sets the maximum number of retries before giving up"`
 
 	// EnableTopologyDiscovery enables the process of discovering the cluster
 	// topology when requests fail.
-	EnableTopologyDiscovery bool
+	EnableTopologyDiscovery bool `desc:"Enables the process of discovering the cluster topology when requests fail"`
 
 	// EnableHealthChecks enables helthchecks of all endpoints in the current cluster topology.
-	EnableHealthChecks bool
+	EnableHealthChecks bool `desc:"Enables helthchecks of all endpoints in the current cluster topology"`
 
-	// HealthCheckTimeout is the timeout in seconds the healthcheck waits for a response
+	// HealthCheckTimeout is the time the healthcheck waits for a response
 	// from a QED server.
-	HealthCheckTimeout time.Duration
+
+	HealthCheckTimeout time.Duration `desc:"Time the healthcheck waits for a response from QED"`
 
 	// AttemptToReviveEndpoints sets if dead endpoints will be marked alive again after a
 	// round-robin round. This way, they will be picked up in the next try.
-	AttemptToReviveEndpoints bool
+	AttemptToReviveEndpoints bool `desc:"Set if dead endpoints will be marked alive again after a round-robin round"`
 }
 
 // DefaultConfig creates a Config structures with default values.

cmd/agent.go

@@ -26,22 +26,32 @@ import (
 )
 
 var agentCmd *cobra.Command = &cobra.Command{
-	Use:              "agent",
-	Short:            "Provides access to the QED gossip agents",
+	Use:   "agent",
+	Short: "Provides access to the QED gossip agents",
+	Long: `QED provides standalone agents to help maintain QED security. We have included
+three agents into the distribution:
+	* Monitor agent: checks the lag of the system between the QED Log and the
+	  Snapshot Store as seen by the gossip network
+	* Auditor agent: verifies QED membership proofs of the snapshots received
+	  throught the  gossip network
+	* Publisher agent: publish snapshots to the snapshot store`,
 	TraverseChildren: true,
 }
 
 var agentCtx context.Context = configAgent()
 
 func init() {
+	agentCmd.MarkFlagRequired("bind-addr")
+	agentCmd.MarkFlagRequired("metrics-addr")
+	agentCmd.MarkFlagRequired("node-name")
+	agentCmd.MarkFlagRequired("role")
+	agentCmd.MarkFlagRequired("log")
 	Root.AddCommand(agentCmd)
 }
 
 func configAgent() context.Context {
-
 	conf := gossip.DefaultConfig()
-	a := &struct{ Agent *gossip.Config }{conf}
-	err := gpflag.ParseTo(a, agentCmd.PersistentFlags())
+	err := gpflag.ParseTo(conf, agentCmd.PersistentFlags())
 	if err != nil {
 		log.Fatalf("err: %v", err)
 	}

cmd/agent_monitor.go

@@ -62,8 +62,12 @@ var (
 )
 
 var agentMonitorCmd *cobra.Command = &cobra.Command{
-	Use:              "monitor",
-	Short:            "Provides access to the QED gossip monitor agent",
+	Use:   "monitor",
+	Short: "Provides access to the QED gossip monitor agent",
+	Long: `Stats a QED monitor which process gossip messages measuring
+the lag between the gossip received messages and the contents of the
+snapshotsore. It also executes incremental proof verification against
+some of the snapshots received.`,
 	TraverseChildren: true,
 	RunE:             runAgentMonitor,
 }

cmd/client_incremental.go

@@ -46,9 +46,9 @@ func init() {
 }
 
 type incrementalParams struct {
-	Start  uint64
-	End    uint64
-	Verify bool
+	Start  uint64 `desc:"Starting version for the incremental proof"`
+	End    uint64 `desc:"Endind version for the incremental proof"`
+	Verify bool   `desc:"Set to enable proof verification process"`
 }
 
 func configClientIncremental() context.Context {

cmd/client_membership.go

@@ -49,10 +49,10 @@ func init() {
 }
 
 type membershipParams struct {
-	Version     uint64
-	Verify      bool
-	Event       string
-	EventDigest string
+	Version     uint64 `desc:"Version for the membership proof"`
+	Verify      bool   `desc:"Set to enable proof verification process"`
+	Event       string `desc:"QED event to build the proof"`
+	EventDigest string `desc:"QED event digest to build the proof"`
 }
 
 func configClientMembership() context.Context {

cmd/server.go

@@ -26,8 +26,10 @@ import (
 )
 
 var serverCmd *cobra.Command = &cobra.Command{
-	Use:              "server",
-	Short:            "Provices access to the QED log server commands",
+	Use:   "server",
+	Short: "Provices access to the QED log server commands",
+	Long: `QED serves provides a REST API to the QED Log. The API is documented
+elsewhere.`,
 	TraverseChildren: true,
 }
 

gossip/config.go

@@ -43,54 +43,54 @@ func DefaultConfig() *Config {
 
 // Config is the configuration for creating an Agent instance
 type Config struct {
-	Log string
+	Log string `desc:"Set log level to info, error or debug"`
 
 	// The name of this node. This must be unique in the cluster. If this
 	// is not set, Auditor will set it to the hostname of the running machine.
-	NodeName string
+	NodeName string `desc:"Set gossip name for this agent"`
 
-	Role string
+	Role string `desc:"Set gossip role for this agent routing"`
 
 	// BindAddr is the address that the Auditor agent's communication ports
 	// will bind to. Auditor will use this address to bind to for both TCP
 	// and UDP connections. If no port is present in the address, the default
 	// port will be used.
-	BindAddr string
+	BindAddr string `desc:"Address ip:port to expose gossip protocol"`
 
 	// AdvertiseAddr is the address agent will advertise to
 	// other members of the cluster. Can be used for basic NAT traversal
 	// where both the internal ip:port and external ip:port are known.
-	AdvertiseAddr string
+	AdvertiseAddr string `desc:"Address ip:port to advertise in gossip if our bind addr is not reachable from other agents"`
 
 	// MetricsAddr is the address where the metrics server will expose its
 	// API to enable mterics collectors retrieve them
-	MetricsAddr string
+	MetricsAddr string `desc:"Address ip:port to expose metrics"`
 
-	// LeaveOnTerm controls if the Auditor does a graceful leave when receiving
+	// LeaveOnTerm controls if the agent does a graceful leave when receiving
 	// the TERM signal. Defaults false. This can be changed on reload.
-	LeaveOnTerm bool
+	LeaveOnTerm bool `desc:"Controls if the agent does a graceful leave when receiving the TERM signal"`
 
 	// StartJoin is a list of addresses to attempt to join when the
 	// agent starts. If the agent is unable to communicate with any of these
 	// addresses, then the agent will error and exit.
-	StartJoin []string
+	StartJoin []string `desc:"Address list ip1:port1,ip2:port2... to join other agents and form a gossip network"`
 
 	// EnableCompression specifies whether message compression is enabled
 	// by `github.com/hashicorp/memberlist` when broadcasting events.
-	EnableCompression bool
+	EnableCompression bool `desc:"Specifies whether message compression is enabled when broadcasting events"`
 
 	// BroadcastTimeout is the amount of time to wait for a broadcast
 	// message to be sent to the cluster. Broadcast messages are used for
 	// things like leave messages and force remove messages. If this is not
 	// set, a timeout of 5 seconds will be set.
-	BroadcastTimeout time.Duration
+	BroadcastTimeout time.Duration `desc:"The amount of time to wait for a broadcast message to be sent to the cluster"`
 
 	// LeavePropagateDelay is for our leave (node dead) message to propagate
 	// through the cluster. In particular, we want to stay up long enough to
 	// service any probes from other nodes before they learn about us
 	// leaving and stop probing. Otherwise, we risk getting node failures as
 	// we leave.
-	LeavePropagateDelay time.Duration
+	LeavePropagateDelay time.Duration `desc:"Time for our leave (node dead) message to propagate through the cluster"`
 
 	// MemberlistConfig is the memberlist configuration that Agent will
 	// use to do the underlying membership management and gossip. Some
@@ -104,20 +104,20 @@ type Config struct {
 	//
 	//   * Delegate - Auditor uses a custom delegate.
 	//
-	MemberlistConfig *memberlist.Config
+	MemberlistConfig *memberlist.Config `flag:"-"`
 
 	// Timeout enqueuing elements on a channel
-	TimeoutQueues time.Duration
+	TimeoutQueues time.Duration `desc:"Timeout enqueuing elements on a channel"`
 
 	// Interval to send out messages to other agents
-	ProcessInterval time.Duration
+	ProcessInterval time.Duration `desc:"Interval to send out messages to other agents"`
 
 	// Maximum number of concurrent senders
-	MaxSenders int
+	MaxSenders int `desc:"Maximum number of concurrent senders"`
 
 	// Cache size in bytes to store agent temporal objects.
 	// This cache will evict old objects by default
-	CacheSize int
+	CacheSize int `desc:"Cache size in bytes to store agent temporal objects"`
 }
 
 // AddrParts returns the parts of the BindAddr that should be

gossip/notifier.go

@@ -38,10 +38,10 @@ type Notifier interface {
 }
 
 type DefaultNotifierConfig struct {
-	Servers      []string
-	QueueTimeout time.Duration
-	DialTimeout  time.Duration
-	ReadTimeout  time.Duration
+	Servers      []string      `desc:"Notification service endpoint list http://ip1:port1,http://ip2:port2... "`
+	QueueTimeout time.Duration `desc:"Timeout enqueuing elements on a channel"`
+	DialTimeout  time.Duration `desc:"Timeout dialing the notification service"`
+	ReadTimeout  time.Duration `desc:"Timeout reading the notification service response"`
 }
 
 func NewDefaultNotifierFromConfig(c *DefaultNotifierConfig) *DefaultNotifier {

gossip/store.go

@@ -10,6 +10,7 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/bbva/qed/log"
 	"github.com/bbva/qed/protocol"
 
 	"github.com/bbva/qed/util"
@@ -34,10 +35,10 @@ type RestSnapshotStore struct {
 }
 
 type RestSnapshotStoreConfig struct {
-	Servers      []string
-	QueueTimeout time.Duration
-	DialTimeout  time.Duration
-	ReadTimeout  time.Duration
+	Servers      []string      `desc:"REST snapshot store service endpoint list http://ip1:port1,http://ip2:port2... "`
+	QueueTimeout time.Duration `desc:"Timeout enqueuing elements on a channel"`
+	DialTimeout  time.Duration `desc:"Timeout dialing the REST snapshot store service"`
+	ReadTimeout  time.Duration `desc:"Timeout reading the REST snapshot store service response"`
 }
 
 func NewRestSnapshotStoreFromConfig(c *RestSnapshotStoreConfig) *RestSnapshotStore {
@@ -73,6 +74,9 @@ func (r *RestSnapshotStore) PutBatch(b *protocol.BatchSnapshots) error {
 		return err
 	}
 	n := len(r.endpoints)
+	if n == 0 {
+		log.Errorf("No endpoints configured for snapshot store!")
+	}
 	server := r.endpoints[0]
 	if n > 1 {
 		server = r.endpoints[rand.Intn(n)]

gossip/taskmanager.go

@@ -69,9 +69,9 @@ type TasksManager interface {
 }
 
 type DefaultTasksManagerConfig struct {
-	QueueTimeout time.Duration
-	Interval     time.Duration
-	MaxTasks     int
+	QueueTimeout time.Duration `desc:"Timeout enqueuing elements on a channel"`
+	Interval     time.Duration `desc:"Interval to execute enqueued tasks"`
+	MaxTasks     int           `desc:"Maximum number of concurrent tasks"`
 }
 
 func NewDefaultTasksManagerFromConfig(c *DefaultTasksManagerConfig) *DefaultTasksManager {