iscdhcp

README

Brief

This is a config-file parser and generator library for ISC-DHCP, written in the Go programming language.

The parser is generated using the goyacc utility.

Supported statements to date include a common subset of those used by DHCPd. The code should be easy to extend.

Usage

Parsing

fd, err := os.Open(fileName)
if err != nil {
    log.Fatalf("os.Open(%q): %s", fileName, err)
}

statements, err := iscdhcp.Decode(fd)
if err != nil {
    log.Fatalf("iscdhcp.Decode(): %s", err)
}

Generating

hs := HostStatement{
    Hostname: "serverA.myDomain.tld",
}
hs.Statements = append(hs.Statements, HardwareStatement{"ethernet", "0:1:2:3:4:5"})
hs.Statements = append(hs.Statements, FixedAddressStatement{net.ParseIP("1.2.3.4")})
hs.Statements = append(hs.Statements, IncludeStatement{"filename.cfg"})

subnetStmt := SubnetStatement{
    SubnetNumber: net.ParseIP("1.2.3.0"),
    Netmask:      net.ParseIP("255.255.255.0"),
}
subnetStmt.Statements = append(subnetStmt.Statements, hs)

fmt.Println(subnetStmt.IndentedString(""))

The above yields this:

subnet 1.2.3.0 netmask 255.255.255.0 {
    host serverA.myDomain.tld {
        hardware ethernet 0:1:2:3:4:5;
        fixed-address 1.2.3.4;
        include "filename.cfg";
    }
}

Modifying

New statements must first be defined in statements.go, and satisfy the iscdhcp.Statement interface.

To update the parser, edit the goyacc grammar definitions in the parser.y file. After updating these you must call goyacc parser.y to regenerate the y.go file, after which you can rebuild the package.

To update generator code, edit the IndentedString() method of the statements with which you're concerned.

It's best to modify both parser- and generator-code in lockstep, and add "round-trip" tests for any new statements introduced to ensure that the generated output is understandable to the parser. Round-trip tests are found in statements_test.go.

Contributing

Contributions should be submitted as pull requests from a named (i.e. not master) branch.

Running make (and the unit tests and linter checks it entails) on the result of merging or rebasing your PR branch over current master branch must exit successfully.

Documentation

Overview

Code generated by goyacc -o y.go -l parse.y. DO NOT EDIT.

Index

• Constants
• type AuthoritativeStatement
  • func (as AuthoritativeStatement) IndentedString(prefix string) string
• type BooleanExpression
• type ConditionalStatement
  • func (cs ConditionalStatement) IndentedString(prefix string) string
• type DomainNameServersOption
  • func (dnso DomainNameServersOption) IndentedString(prefix string) string
• type FixedAddressStatement
  • func (fas FixedAddressStatement) IndentedString(prefix string) string
• type GroupStatement
  • func (gs GroupStatement) IndentedString(prefix string) string
• type HardwareStatement
  • func (hs HardwareStatement) IndentedString(prefix string) string
• type HostStatement
  • func (hs HostStatement) IndentedString(prefix string) string
• type IncludeStatement
  • func (is IncludeStatement) IndentedString(prefix string) string
• type PacketOptionTerm
  • func (pot PacketOptionTerm) String() string
• type Statement
  • func Decode(dataStream io.Reader) ([]Statement, error)
• type StringConstTerm
  • func (sct StringConstTerm) String() string
• type SubnetStatement
  • func (sns SubnetStatement) IndentedString(prefix string) string
• type UseHostDeclNamesStatement
  • func (uhdns UseHostDeclNamesStatement) IndentedString(prefix string) string

Constants

const BoolAnd = 57354

const BoolEqual = 57357

const BoolExists = 57361

const BoolInequal = 57358

const BoolKnown = 57362

const BoolNot = 57356

const BoolOr = 57355

const BoolRegexIMatch = 57360

const BoolRegexMatch = 57359

const BoolStatic = 57363

const ConditionElse = 57353

const ConditionElsif = 57352

const ConditionIf = 57351

Types

type AuthoritativeStatement

type AuthoritativeStatement bool

An AuthoritativeStatement represents an "authoritative" parameter. See "The authoritative statement" in dhcpd.conf(5)

func (AuthoritativeStatement) IndentedString

func (as AuthoritativeStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type BooleanExpression

type BooleanExpression struct {
	// Operator is one of the boolean operators specified in dhcp-eval(5),
	// represented by the integer constants in this package beginning with
	// "Bool", e.g. BoolAnd, BoolOr, BoolEqual etc.
	//
	// The Operator specified will apply to either the BoolTerms or the
	// DataTerms supplied with the BooleanExpression.
	Operator int // one of boolOpStrings(...)
	// A BooleanExpression may apply an operator to the output of sub-
	// -expressions, e.g. the "and" operator in the algebraic expression
	// (x > 1) and (x < 10). In this case, the sub-expressions should be
	// specified under the BoolTerms field.
	BoolTerms []BooleanExpression
	// A BooleanExpression will otherwise apply to comparisons or operations
	// on data values, e.g. "if x = 'foo'". In this case, the sub-expressions
	// should be specified under the DataTerms field.
	DataTerms []fmt.Stringer
}

A BooleanExpression is an expression of terms and operators which can be evaluated into a single true or false value. BooleanExpressions are used to determine if the statements within a ConditionalStatement will be evaluated. See dhcp-eval(5) for more information.

type ConditionalStatement

type ConditionalStatement struct {
	// Operator is one of if/elsif/else, represented by the integers
	// {ConditionIf, ConditionElsif, ConditionElse}.
	Operator int
	// Condition is the expression immediately following the "if/elsif" word,
	// which determines if the other Statements within this ConditionalStatement
	// are evaluated. It is unnecessary / will be ignored for "else"
	// sub-conditionals.
	Condition BooleanExpression
	// Statements is the list of Statements which will be evaluated if Condition
	// proves True.
	Statements []Statement
	// SubConditionals is a list of elsif/else ConditionalStatements, whose
	// evaluation is predicated on the top-level statement not being evaluated,
	// and their own Conditions proving True.
	SubConditionals []ConditionalStatement
}

A ConditionalStatement represents a conditional-evaluation statement in a config file, a la dhcp-eval(5).

Each top-level ConditionalStatement must be an if-statement; it may optionally have else-if and else sub ConditionalStatements.

Each ConditionalStatement also contains a block of other Statements.

Example usage:

cs := ConditionalStatement{
	Operator: ConditionIf,
	Condition: BooleanExpression {
		Operator: BoolEqual,
		DataTerms: []fmt.Stringer {
			PacketOptionTerm{"user-class"},
			StringConstTerm("iPXE"),
		},
	},
	SubConditionals: []ConditionalStatement {
		{
			Operator: ConditionElse,
		},
	},
}
cs.Statements = []Statement{IncludeStatement{"ipxe.conf"}}
cs.SubConditionals[0].Statements = []Statement{IncludeStatement{"non-ipxe.conf"}}

This example corresponds to the following config-file text:

if option user-class = "iPXE" {
	include "ipxe.conf";
}
else {
	include "non-ipxe.conf";
}

func (ConditionalStatement) IndentedString

func (cs ConditionalStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type DomainNameServersOption

type DomainNameServersOption []net.IP

A DomainNameServersOption represents a domain-name-servers option parameter. See "option domain-name-servers" in dhcp-options(5)

func (DomainNameServersOption) IndentedString

func (dnso DomainNameServersOption) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type FixedAddressStatement

type FixedAddressStatement []net.IP

A FixedAddressStatement represents a fixed-address parameter. See "The fixed-address declaration" in dhcpd.conf(5)

func (FixedAddressStatement) IndentedString

func (fas FixedAddressStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type GroupStatement

type GroupStatement struct {
	Statements []Statement
}

A GroupStatement represents a group declaration. See "The group statement" in dhcpd.conf(5)

func (GroupStatement) IndentedString

func (gs GroupStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type HardwareStatement

type HardwareStatement struct {
	HardwareType    string
	HardwareAddress string
}

A HardwareStatement represents a hardware parameter. See "The hardware statement" in dhcpd.conf(5)

func (HardwareStatement) IndentedString

func (hs HardwareStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type HostStatement

type HostStatement struct {
	Hostname   string
	Statements []Statement
}

A HostStatement represents a host declaration. See "The host statement" in dhcpd.conf(5)

func (HostStatement) IndentedString

func (hs HostStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type IncludeStatement

type IncludeStatement struct {
	Filename string
}

An IncludeStatement represents an include-file declaration. See "The include statement" in dhcpd.conf(5)

func (IncludeStatement) IndentedString

func (is IncludeStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type PacketOptionTerm

type PacketOptionTerm struct {
	// contains filtered or unexported fields
}

A PacketOptionTerm is a data-term used in a BooleanExpression. It represents an option in a DHCP packet, and is stringified for config file syntax like “option user-class”.

func (PacketOptionTerm) String

func (pot PacketOptionTerm) String() string

type Statement

type Statement interface {
	// IndentedString produces string representation of the config statement,
	// in the form expected by dhcpd. The "prefix" argument is used to indent
	// nested statements; it is not a standard indent-depth, but an explicit
	// prefix for this particular statement's string representation.
	// FIXME It'd really be nice to be able to configure the standard depth.
	IndentedString(prefix string) string
}

A Statement represents an ISC-DHCP configuration statement. See dhcpd.conf(5) dhcp-options(5) and dhcpd-eval(5) for canonical types. For implementations, see "go doc iscdhcp | grep Statement".

func Decode

func Decode(dataStream io.Reader) ([]Statement, error)

Decode analyzes a slice of bytes, constructing primitive ISC-DHCP config objects.

type StringConstTerm

type StringConstTerm string

A StringConstTerm is a data-term used in a BooleanExpression. It represents a quote-enclosed arbitrary string, e.g. “"foo"”.

func (StringConstTerm) String

func (sct StringConstTerm) String() string

type SubnetStatement

type SubnetStatement struct {
	SubnetNumber net.IP
	Netmask      net.IP
	Statements   []Statement
}

A SubnetStatement represents a subnet declaration. See "The subnet statement" in dhcpd.conf(5)

func (SubnetStatement) IndentedString

func (sns SubnetStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface

type UseHostDeclNamesStatement

type UseHostDeclNamesStatement bool

A UseHostDeclNamesStatement represents a "use-host-decl-names" parameter. See "The use-host-decl-names statement" in dhcpd.conf(5)

func (UseHostDeclNamesStatement) IndentedString

func (uhdns UseHostDeclNamesStatement) IndentedString(prefix string) string

IndentedString implements the method of the same name in the Statement interface