FreeCONF plays an important role in the greater mission to browse, inspect and program every piece of running software in your entire IT infrastructure!

FreeCONF is a library for adding IETF standards support for configuration, metrics, operations and events to any service written in the Go programming language.

Why?

Every services needs integration with IT tools that provide:

1. fault monitoring
2. configuration management
3. administration API
4. performance metrics and analysis
5. security

With just 5 different services you would need to develop and maintain 25 custom integration scripts or plugins.

However with a management standard there are NO integration scripts or plugins to write.

How does it work?

Every running service publishes one or more files called "YANG files" describing their management capabilities. IT tools can then read these "YANG files" directly from the running service to discover the service's management capabilties. Once the management capabilties are known, IT tools can manage the running service even though it had no prior knowledge of the service.

For example let's say you wrote a new toaster service and you wanted it to be manageable.

Steps as a developer:

1. Describe the management capabilities of the toaster in a YANG file like this one..
2. Use FreeCONF library (or any other library that supports proper server-side IETF RFCs) to serve YANG files and help developer implement the management capabilties.

Steps as a operator:

1. Start toaster service within your IT infrastruture (doesn't matter how : docker container, bare metal or physical device).
2. Choose an alert service as part of your IT infrastructure (or write your own with FreeCONF) that supports proper client-side IETF RFCs.
3. Alert service will read selected services and discover there are two events exported by the toaster service: toasterOutOfBread and toasterRestocked. Alert service can then ask any operator which events they'd like to be notified about.

How does this compare to ___?

Most likely FreeCONF complements what you're using today for management. There are no agents to install, plugins to build or servers to start.

Source code

Requires Go version 1.9 or greater and uses go dep to manage the one dependencies on golang.org/x/net.

If you just want to quickly download the source into your project, you can use this command:

go get -d -u github.com/freeconf/gconf/...

Benefits

• Supports IETF management standards:
  • YANG
  • YANG 1.1
  • RESTCONF
  • Call Home
• no dependencies beyond Go Standard Library and Go's net package
• code generation optional
• no code annotations (i.e. "go tags") required
• documentation generator
• client and server support including examples

License

Licensed under Apache 2.0 license.

Getting started

Full source for this example is here.

Step 1. Write your application as you normally would

Here we are implementing a car application.

type Car struct {
	Speed     int
	Miles     int64
}

func (c *Car) Start() {
	for {
		<-time.After(time.Duration(c.Speed) * time.Millisecond)
		c.Miles += 1
	}
}

Step 2. Model your application in YANG

Use YANG to model your management API.

module car {

	revision 0;
	
	leaf speed {
	   type int32;
	}	    	    

	leaf miles {
	   type int64;
	   config false;
	}	    	    

	notification update {
		leaf state {
			type enumeration {
				enum outOfGas;
				enum running;
			}
		}
	}
	
	rpc start {}
}

Step 3. Add Management

// implement your mangement api
func manage(car *Car) node.Node {
	return &nodes.Extend {
	
		// use reflect when possible, here we're using to get/set speed AND
		// to read miles metrics.
		Base: nodeutil.ReflectChild(car),

		// handle action request
		OnAction: func(parent node.Node, req node.ActionRequest) (node.Node, error) {
			switch req.Meta.Ident() {
			case "start":
				go car.Start()
			}
			return nil, nil
		},
		
		...
	}
}

Step 4. Connect everything together

import (
	"github.com/freeconf/gconf/restconf"
	"github.com/freeconf/gconf/meta/yang"
	"github.com/freeconf/gconf/nodes"
	"github.com/freeconf/gconf/device"
)

func main() {

	// Your app
	car := &Car{}
		
	// Add management
	d := device.New(parser.YangPath())
	d.Add("car", manage(car)) 
	
	// Select wire-protocol
	restconf.NewServer(d)
	
	// apply start-up config
	d.ApplyStartupConfig(os.Stdin)
		
	// trick to sleep forever...
	select {}
}

Step 5. Using your management API

Start your application

YANGPATH=.:../../gconf/yang \
    go run ./main.go <<< \
      '{"restconf":{\
          "web":{"port":":8080"}},\
          "car":{}}'

Get Configuration

curl http://localhost:8080/restconf/data/car:?content=config

{"speed":100}

Change Configuration

curl -XPUT -d @- http://localhost:8080/restconf/data/car: <<< '{"speed":99}'

Metrics

curl http://localhost:8080/restconf/data/car:?content=nonconfig

{"miles":133}

Operations

Start has no input or output defined, so simple POST will start the car

curl -XPOST http://localhost:8080/restconf/data/car:start

Alerts

To get updates to the car status, one options is to use websockets from Node.js or the web browser:

var notify = require('./notify');
...
var events = new notify.handler(ws_driver);
events.on('', 'update', 'car', (car, err) => {
  console.log(car);
});

Security

Default authenication is certificate based and default authorization is based on the YANG model from Step 2.. of any management operation based on whatever authentication management you decide. Each configuration change is logged by the server.

More Examples

• Robotic Bartender - Pour drinks automatically from Raspberry Pi
• App Examples - Complete applications that each have management APIs.
• Code Examples - Mostly examples on management node handlers options.
• Example generated docs. Templates exist for Markdown, HTML and SVG (thru dot)
  • Car Doc - Car example generated doc.
  • Car Model - Graphical representation
  • RESTConf Doc - RESTConf is itself managable.
• Example YANG files - Used internally by FreeCONF
• Industry YANG files - From openconfig.net project
• More Industry YANG files - From yangcatalog.org project

Resources

• YANG/RESTCONF on wikipedia
• Slides on why we need a DevOps standards from an operatator's perspective and a developer's perspective.
• Manual - Work in progress