xref: /netbsd-src/external/bsd/nsd/dist/doc/NEW-CFG-OPTION (revision d83a80ee7fb31190352cf1f781441e06ca6a86db)

When adding a new configuration option to NSD, several files need to be
touched. This file is an enumeration of files that need to be edited.
Suppose we are going to add a configuration option 'dummy:' that can take
a string. We need to update the following files:

	1. configlexer.lex
	2. configparser.y
	3. options.h
	4. options.c
	5. nsd.conf.sample.in
	6. nsd.conf.5.in
	7. nsd-checkconf.c
	8. tpkg/checkconf.tpkg

1. Update configlexer.lex

Make sure that zonec understands the new option by adding the following
line into configlexer.lex

	dummy{COLON}  { LEXOUT(("v(%s) ", yytext)); return VAR_DUMMY;}

2. Update configparser.y

Make sure that zonec can parse the new option by adding VAR_DUMMY to the set
of tokens:

	%token VAR_DUMMY

Update the grammar. For example, if it a server option, extend content_server:

	content_server: server_ip_address | ...
		server_hide_version | server_dummy;

And write down the dummy rule:

	server_dummy: VAR_DUMMY STRING
        {
                OUTYY(("P(server_dummy:%s)\n", $2));
                cfg_parser->opt->dummy =
			region_strdup(cfg_parser->opt->region, $2);
        }
        ;

3. Update options.h

Make sure that there is storage for the dummy option. In struct nsd_options,
add:

	const char* dummy;

4. Update options.c

Set a default dummy string. In the function nsd_options_create(), add:

	opt->dummy = "dummy";

5. Update nsd.conf.sample.in

Add a reference in the sample configuration file:

	# This option does nothing.
	# dummy: "dummy"

6. Update nsd.conf.5.in

Update the nsd.conf manpage:

	.TP
	.B dummy:\fR <filename>
	Does nothing.

7. Update nsd-checkconf.c

Make the checkconf tool aware of the new option. In config_print_zone(), add:

	SERV_GET_STR(dummy, o);

and in config_test_print_server(), add:

	print_string_var("dummy:", opt->dummy);

8. Update tpkg/checkconf.tpkg

Make the test aware of the new option. Extract checkconf.tpkg:

	$ cd tpkg;
	$ tpkg extract checkconf.tpkg
	$ cd checkconf.dir

And add to the various checkconf.check[1-9] files:

	dummy: "dummy"

Go back to the tpkg directory and create the new test:

	$ cd ..
	$ tpkg create checkconf.tpkg

9. Update other files

You might need to edit other files too:

- If the new option requires to be enabled at build time, you need to add
  stuff to configure.ac and Makefile.in.

- Update documentation files, like doc/README, doc/RELNOTES, doc/Changelog.

- Obviously, the source code files need to be edited to implement the new
  functionality.