Software tail-f ConfD User guide

ConfD User Guide

ConfD 6.6

March 2, 2018

ConfD User Guide

ConfD 6.6

Publication date March 2, 2018

All contents in this document are confidential and proprietary to Tail-f Systems.

Table of Contents

1. About the Documentation ................................................................................................. 1

1.1. How to Read This Guide ........................................................................................ 1

1.2. Getting Documentation .......................................................................................... 1

1.3. Formatting Conventions ......................................................................................... 1

1.4. Documentation Feedback ........................................................................................ 2

2. An introduction to ConfD ................................................................................................. 3

2.1. An on-device software system for configuration management ........................................ 3

2.2. ConfD Architecture ............................................................................................... 3

3. The YANG Data Modeling Language ................................................................................. 8

3.1. The YANG Data Modeling Language ....................................................................... 8

3.2. YANG in ConfD .................................................................................................. 8

3.3. YANG Introduction ............................................................................................... 8

3.4. Working With YANG Modules ............................................................................. 16

3.5. Integrity Constraints ............................................................................................. 18

3.6. The when statement ............................................................................................. 20

3.7. Using the Tail-f Extensions with YANG ................................................................. 20

3.8. Custom Help Texts and Error Messages .................................................................. 22

3.9. Hidden Data ....................................................................................................... 24

3.10. An Example: Modeling a List of Interfaces ............................................................ 26

3.11. More on leafrefs ................................................................................................ 34

3.12. Using Multiple Namespaces ................................................................................ 36

3.13. Module Names, Namespaces and Revisions ............................................................ 37

3.14. Hash Values and the id-value Statement ................................................................ 38

3.15. Migrating from Confspecs to YANG ..................................................................... 39

3.16. The pyang tool .................................................................................................. 44

4. Rendering Agents .......................................................................................................... 45

4.1. Introduction ........................................................................................................ 45

4.2. Data Model ........................................................................................................ 45

4.3. Using the CLIs ................................................................................................... 47

4.4. Using NETCONF ................................................................................................ 50

5. CDB - The ConfD XML Database .................................................................................... 53

5.1. Introduction ........................................................................................................ 53

5.2. CDB ................................................................................................................. 53

5.3. An example ........................................................................................................ 54

5.4. Using keypaths ................................................................................................... 58

5.5. A session ........................................................................................................... 59

5.6. CDB subscriptions ............................................................................................... 60

5.7. Reconnect .......................................................................................................... 61

5.8. Loading initial data into CDB ................................................................................ 62

5.9. Automatic schema upgrades and downgrades ........................................................... 63

5.10. Using initialization files for upgrade ..................................................................... 68

5.11. Using MAAPI to modify CDB during upgrade ........................................................ 71

5.12. More complex schema upgrades ........................................................................... 72

5.13. The full dhcpd example ...................................................................................... 75

6. Operational Data ............................................................................................................ 82

6.1. Introduction to Operational Data ............................................................................ 82

6.2. Reading Statistics Data ......................................................................................... 82

6.3. Callpoints and Callbacks ...................................................................................... 83

6.4. Data Callbacks .................................................................................................... 85

6.5. User Sessions and ConfD Transactions .................................................................... 87

6.6. C Example with Operational Data .......................................................................... 87

iii

ConfD User Guide

6.7. The Protocol and a Library Threads Discussion ........................................................ 95

6.8. Operational data in CDB ...................................................................................... 97

6.9. Delayed Replies ................................................................................................ 100

6.10. Caching Operational Data .................................................................................. 101

6.11. Operational data lists without keys ...................................................................... 102

7. The external database API ............................................................................................. 104

7.1. Introduction to external data ................................................................................ 104

7.2. Scenario - The database is a file ........................................................................... 104

7.3. Callpoints and callbacks ...................................................................................... 104

7.4. Data Callbacks .................................................................................................. 105

7.5. User sessions and ConfD Transactions .................................................................. 105

7.6. External configuration data .................................................................................. 108

7.7. External configuration data with transactions .......................................................... 112

7.8. Writable operational data .................................................................................... 116

7.9. Supporting candidate commit ............................................................................... 116

7.10. Discussion - CDB versus external DB ................................................................. 118

8. Configuration Meta-Data ............................................................................................... 120

8.1. Introduction to Configuration Meta-Data ................................................................ 120

8.2. Meta-Data: annotation .................................................................................. 120

8.3. Meta-Data: tag ................................................................................................ 120

8.4. Meta-Data: inactive ...................................................................................... 121

9. Semantic validation ...................................................................................................... 122

9.1. Why Do We Need to Validate ............................................................................. 122

9.2. Syntactic Validation in YANG models .................................................................. 122

9.3. Integrity Constraints in YANG Models .................................................................. 122

9.4. The YANG must Statement ................................................................................. 123

9.5. Validation Logic ................................................................................................ 123

9.6. Validation Points ............................................................................................... 124

9.7. Validating Data in C .......................................................................................... 125

9.8. Validation Points and CDB ................................................................................. 130

9.9. Dependencies - Why Does Validation Points Get Called ........................................... 130

9.10. Configuration Policies ....................................................................................... 132

10. Transformations, Hooks, Hidden Data and Symlinks ......................................................... 134

10.1. Introduction ..................................................................................................... 134

10.2. Transformation Control Flow ............................................................................. 134

10.3. An Example .................................................................................................... 135

10.4. AAA Transform ............................................................................................... 140

10.5. Other Use Cases for Transformations .................................................................. 142

10.6. Hooks ............................................................................................................ 143

10.7. Hidden Data .................................................................................................... 146

10.8. tailf:symlink .................................................................................................... 148

11. Actions ..................................................................................................................... 151

11.1. Introduction ..................................................................................................... 151

11.2. Action as a Callback ........................................................................................ 151

11.3. Action as an Executable .................................................................................... 154

11.4. Related functionality ......................................................................................... 157

12. Notifications .............................................................................................................. 159

12.1. ConfD Asynchronous Events ............................................................................. 159

12.2. Audit Messages ............................................................................................... 160

12.3. Syslog Messages .............................................................................................. 162

12.4. Commit Events ................................................................................................ 162

12.5. Commit Failure Events ..................................................................................... 165

12.6. Confirmed Commit Events ................................................................................ 165

12.7. Commit Progress Events ................................................................................... 165

iv

ConfD User Guide

12.8. User Sessions .................................................................................................. 165

12.9. High Availability - Cluster Events ...................................................................... 166

12.10. Subagent Events ............................................................................................. 167

12.11. SNMP Agent Audit Log .................................................................................. 168

12.12. Forwarding Events .......................................................................................... 170

12.13. In-service Upgrade Events ............................................................................... 170

12.14. Heartbeat and Health Check Events ................................................................... 170

12.15. Notification stream Events ............................................................................... 170

13. In-service Data Model Upgrade .................................................................................... 171

13.1. Introduction ..................................................................................................... 171

13.2. Preparing for the Upgrade ................................................................................. 171

13.3. Initializing the Upgrade ..................................................................................... 172

13.4. Performing the Upgrade .................................................................................... 173

13.5. Committing the Upgrade ................................................................................... 173

13.6. Aborting the Upgrade ....................................................................................... 174

13.7. Upgrade and HA .............................................................................................. 174

14. The AAA infrastructure ............................................................................................... 176

14.1. The problem .................................................................................................... 176

14.2. Structure - data models ..................................................................................... 176

14.3. AAA related items in confd.conf ........................................................................ 177

14.4. Authentication ................................................................................................. 178

14.5. Group Membership ........................................................................................... 186

14.6. Authorization .................................................................................................. 187

14.7. The AAA cache ............................................................................................... 200

14.8. Populating AAA using CDB .............................................................................. 200

14.9. Populating AAA using external data .................................................................... 200

14.10. Hiding the AAA tree ...................................................................................... 201

15. The NETCONF Server ................................................................................................ 202

15.1. Introduction ..................................................................................................... 202

15.2. Capabilities ..................................................................................................... 203

15.3. NETCONF Transport Protocols .......................................................................... 206

15.4. Configuration of the NETCONF Server ............................................................... 208

15.5. Extending the NETCONF Server ........................................................................ 209

15.6. Monitoring of the NETCONF Server ................................................................... 214

15.7. Notification Capability ...................................................................................... 214

15.8. Using netconf-console ....................................................................................... 218

15.9. Actions Capability ............................................................................................ 219

15.10. Transactions Capability ................................................................................... 222

15.11. Proxy Forwarding Capability ............................................................................ 227

15.12. Inactive Capability .......................................................................................... 237

15.13. Tail-f Identification Capability .......................................................................... 239

15.14. The Query API .............................................................................................. 240

15.15. Meta-data in Attributes .................................................................................... 244

15.16. Namespace for Additional Error Information ....................................................... 245

16. The CLI agent ........................................................................................................... 248

16.1. Overview ........................................................................................................ 248

16.2. The J-style CLI ............................................................................................... 249

16.3. The C- and I-style CLI ..................................................................................... 251

16.4. The CLI in action ............................................................................................ 252

16.5. Environment for OS command execution ............................................................. 254

16.6. Command output processing .............................................................................. 254

16.7. Range expressions ............................................................................................ 261

16.8. Autorendering of enabled/disabled ...................................................................... 263

16.9. Actions ........................................................................................................... 263

v

ConfD User Guide

16.10. Command history ........................................................................................... 264

16.11. Clearing history ............................................................................................. 264

16.12. Command line editing ..................................................................................... 264

16.13. Using CLI completion ..................................................................................... 266

16.14. Using the comment characters # or ! .................................................................. 269

16.15. Annotations and tags ....................................................................................... 270

16.16. Activate and Deactivate ................................................................................... 271

16.17. CLI messages ................................................................................................ 272

16.18. confd.conf settings .......................................................................................... 273

16.19. CLI Environment ........................................................................................... 273

16.20. Commands in J-style ....................................................................................... 275

16.21. Commands in C/I-style .................................................................................... 287

16.22. Customizing the CLI ....................................................................................... 299

16.23. User defined wizards ...................................................................................... 305

16.24. User defined wizards in C ................................................................................ 308

16.25. User defined commands in C using the C-API ..................................................... 310

16.26. User defined commands as shell scripts .............................................................. 311

16.27. Modifying built-in commands ........................................................................... 311

16.28. Tailoring show commands ............................................................................... 312

16.29. Change password at initial login ....................................................................... 317

17. The SNMP Agent ....................................................................................................... 319

17.1. Introduction to the ConfD SNMP Agent .............................................................. 319

17.2. Agent Functional Description ............................................................................. 320

17.3. Generating MIBs from YANG ........................................................................... 339

17.4. Configuring the SNMP Agent ............................................................................ 342

17.5. How the SNMP Agent Interacts with ConfD ......................................................... 346

17.6. Running the SNMP Agent as a NET-SNMP subagent ............................................. 347

18. Web UI Development ................................................................................................. 349

18.1. Introduction ..................................................................................................... 349

18.2. Example of a common flow ............................................................................... 350

18.3. Example of a JSON-RPC client .......................................................................... 354

18.4. Example of a Comet client ................................................................................ 357

19. The JSON-RPC API ................................................................................................... 361

19.1. JSON-RPC ...................................................................................................... 361

19.2. Methods - commands ........................................................................................ 366

19.3. Methods - commands - subscribe ........................................................................ 368

19.4. Methods - data ................................................................................................ 373

19.5. Methods - data - attrs ....................................................................................... 375

19.6. Methods - data - leafs ....................................................................................... 376

19.7. Methods - data - leafref .................................................................................... 378

19.8. Methods - data - lists ........................................................................................ 379

19.9. Methods - data - query ...................................................................................... 382

19.10. Methods - database ......................................................................................... 386

19.11. Methods - general ........................................................................................... 387

19.12. Methods - messages ........................................................................................ 390

19.13. Methods - rollbacks ........................................................................................ 391

19.14. Methods - schema .......................................................................................... 393

19.15. Methods - session ........................................................................................... 400

19.16. Methods - session data .................................................................................... 402

19.17. Methods - transaction ...................................................................................... 403

19.18. Methods - transaction - changes ........................................................................ 406

19.19. Methods - transaction - commit changes ............................................................. 408

19.20. Methods - transaction - webui .......................................................................... 410

20. The web server .......................................................................................................... 411

vi

ConfD User Guide

20.1. Introduction ..................................................................................................... 411

20.2. Web server capabilities ..................................................................................... 411

20.3. CGI support .................................................................................................... 411

21. The REST API .......................................................................................................... 414

21.1. Introduction ..................................................................................................... 414

21.2. Getting started ................................................................................................. 414

21.3. Resource Examples .......................................................................................... 424

21.4. Resources ....................................................................................................... 438

21.5. Configuration Meta-Data ................................................................................... 448

21.6. Request/Response headers ................................................................................. 449

21.7. Special characters ............................................................................................. 450

21.8. Error Responses ............................................................................................... 452

21.9. The Query API ................................................................................................ 454

21.10. Custom Response HTTP Headers ...................................................................... 459

21.11. HTTP Status Codes ........................................................................................ 460

22. The RESTCONF API .................................................................................................. 462

22.1. Introduction ..................................................................................................... 462

22.2. Getting started ................................................................................................. 462

22.3. Capabilities ..................................................................................................... 464

22.4. Streams .......................................................................................................... 464

22.5. Schema resource .............................................................................................. 465

22.6. YANG Patch Media Type ................................................................................. 465

22.7. Extensions ...................................................................................................... 465

22.8. Custom Response HTTP Headers ....................................................................... 466

23. The Management Agent API ........................................................................................ 467

23.1. What is MAAPI? ............................................................................................. 467

23.2. A custom toy CLI ............................................................................................ 467

24. High Availability ........................................................................................................ 474

24.1. Introduction to ConfD High Availability .............................................................. 474

24.2. HA framework requirements .............................................................................. 475

24.3. Mode of operation ............................................................................................ 475

24.4. Security aspects ............................................................................................... 477

24.5. API ................................................................................................................ 477

24.6. Ticks .............................................................................................................. 479

24.7. Joining a cluster ............................................................................................... 479

24.8. Relay slaves .................................................................................................... 480

24.9. CDB replication ............................................................................................... 481

25. The SNMP Gateway ................................................................................................... 482

25.1. Introduction to the ConfD SNMP Gateway ........................................................... 482

25.2. Configuring Agent Access ................................................................................. 482

25.3. Compiling the MIBs ......................................................................................... 483

25.4. Receiving and Forwarding Notifications ............................................................... 483

25.5. Example Scenario ............................................................................................ 484

26. Subagents and Proxies ................................................................................................. 485

26.1. Introduction ..................................................................................................... 485

26.2. Subagent Registration ....................................................................................... 486

26.3. Subagent Requirements ..................................................................................... 490

26.4. Proxies ........................................................................................................... 490

27. Plug-and-play scripting ................................................................................................ 496

27.1. Introduction ..................................................................................................... 496

27.2. Script storage .................................................................................................. 496

27.3. Script interface ................................................................................................ 496

27.4. Loading of scripts ............................................................................................ 497

27.5. Command scripts ............................................................................................. 497

vii

ConfD User Guide

27.6. Policy scripts ................................................................................................... 502

27.7. Post-commit scripts .......................................................................................... 505

28. Advanced Topics ........................................................................................................ 508

28.1. Datastores ....................................................................................................... 508

28.2. Locks ............................................................................................................. 510

28.3. Installing ConfD on a target system .................................................................... 512

28.4. Configuring ConfD ........................................................................................... 513

28.5. Starting ConfD ................................................................................................ 515

28.6. ConfD IPC ...................................................................................................... 517

28.7. Restart strategies .............................................................................................. 521

28.8. Security issues ................................................................................................. 522

28.9. Running ConfD as a non privileged user .............................................................. 523

28.10. Storing encrypted values in ConfD .................................................................... 524

28.11. Disaster management ...................................................................................... 527

28.12. Troubleshooting ............................................................................................. 529

28.13. Tuning the size of confd_hkeypath_t .................................................................. 534

28.14. Error Message Customization ........................................................................... 535

28.15. Using a different version of OpenSSL ................................................................ 535

28.16. Using shared memory for schema information ..................................................... 536

28.17. Running application code inside ConfD .............................................................. 538

I. ConfD man-pages, Volume 1 .......................................................................................... 541

confd ..................................................................................................................... 542

confd_aaa_bridge ..................................................................................................... 547

confd_cli ................................................................................................................ 549

confd_cmd ............................................................................................................. 552

confd_load .............................................................................................................. 554

confdc .................................................................................................................... 559

maapi ..................................................................................................................... 570

II. ConfD man-pages, Volume 3 ......................................................................................... 575

confd_lib ................................................................................................................ 576

confd_lib_cdb .......................................................................................................... 577

confd_lib_dp ........................................................................................................... 615

confd_lib_events ...................................................................................................... 675

confd_lib_ha ........................................................................................................... 682

confd_lib_lib ........................................................................................................... 684

confd_lib_maapi ...................................................................................................... 706

confd_types ............................................................................................................. 773

III. ConfD man-pages, Volume 5 ....................................................................................... 814

clispec .................................................................................................................... 815

confd.conf .............................................................................................................. 872

mib_annotations ....................................................................................................... 930

tailf_yang_cli_extensions ........................................................................................... 932

tailf_yang_extensions ................................................................................................ 973

Glossary ....................................................................................................................... 1009

viii

List of Tables

3.1. YANG built-in types .................................................................................................... 12

17.1. SMI mapping to YANG types .................................................................................... 325

17.2. YANG mapping to SMI types .................................................................................... 326

21.1. REST vs NETCONF operations ................................................................................. 416

21.2. Query Parameters ..................................................................................................... 423

21.3. Resources and their Media Types ............................................................................... 439

21.4. Fields of the /api resource .......................................................................................... 440

21.5. Fields of the /api/<datastore> resource ......................................................................... 443

21.6. Built in operations .................................................................................................... 443

21.7. Error code vs HTTP Status ........................................................................................ 454

28.1. ConfD Start Phases .................................................................................................. 516

28.2. ConfD Start Phases, running in foreground ................................................................... 516

ix

List of Examples

5.1. a simple server data model, servers.yang .................................................................. 54

5.2. Pseudo code showing several sessions reusing one connection ............................................. 59

5.3. Pseudo code demonstrating how to avoid re-reading the configuration ................................... 62

5.4. Version 1.0 of the forest module .................................................................................... 63

5.5. Initial forest instance document ..................................................................................... 64

5.6. Version 2.0 of the forest module .................................................................................... 65

5.7. Forest instance document after upgrade ........................................................................... 66

5.8. Enabling the developer log ............................................................................................ 67

5.9. Developer log entries resulting from upgrade ................................................................... 67

5.10. Version 1.5 of the servers.yang module ......................................................................... 69

5.11. Writing to an upgrade transaction using MAAPI ............................................................. 71

5.12. Version 2 of the servers.yang module ............................................................................ 72

5.13. The upgrade() function of server_upgrade.c ...................................................... 73

5.14. A YANG module describing a dhcpd server configuration ................................................ 75

6.1. netstat.yang ................................................................................................................ 82

6.2. ARP table YANG module ............................................................................................ 84

6.3. Populated ARP table .................................................................................................... 85

7.1. A list of server structures ............................................................................................ 104

7.2. The smp.yang module ................................................................................................ 108

7.3. get_next() callback for smp.yang .................................................................................. 110

7.4. create() callback for smp.yang ..................................................................................... 111

7.5. remove() callback for smp.yang ................................................................................... 111

7.6. set_elem() callback for smp.yang .................................................................................. 111

7.7. save() utility function ................................................................................................. 112

7.8. write callbacks using accumulate .................................................................................. 113

7.9. prepare() callback using the accumulated write ops .......................................................... 114

7.10. commit() and abort() ................................................................................................ 115

7.11. Code to restore our array from a file ........................................................................... 116

7.12. checkpoint db callbacks ............................................................................................ 117

10.1. full.yang ................................................................................................................. 135

10.2. small.yang .............................................................................................................. 135

10.3. users.yang ............................................................................................................... 140

12.1. Creating a notification socket ..................................................................................... 160

12.2. reading the audit data ............................................................................................... 160

15.1. Example math rpc .................................................................................................... 210

17.1. Simple YANG module .............................................................................................. 323

17.2. Generating and compiling YANG from MIB ................................................................ 328

17.3. The YANG file generated by confdc --mib2yang .......................................................... 328

17.4. Specifying built-in MIBs to be loaded into the agent ...................................................... 331

17.5. SMI definition of an optional object ............................................................................ 333

17.6. YANG definition of an optional leaf ........................................................................... 334

17.7. simple.mib .............................................................................................................. 334

17.8. simple.yang ............................................................................................................. 335

17.9. simple.yang with secondary index ............................................................................... 335

17.10. TruthValue from the SNMPv2-TC ............................................................................. 336

17.11. A typedef for TruthValue ........................................................................................ 336

17.12. Functions for sending notification from C ................................................................... 337

17.13. SNMP varbind structures from confd_maapi.h ....................................................... 337

17.14. Notification registration ........................................................................................... 338

17.15. Sending a coldStart notification ................................................................................ 338

17.16. Sending a notification with a varbind ......................................................................... 338

x

ConfD User Guide

17.17. Example of a confd.conf .......................................................................................... 343

17.18. Old confd.conf content ............................................................................................ 344

17.19. Updated confd.conf content ...................................................................................... 344

17.20. Example community_init.xml ................................................................................... 345

19.1. Method get_value ..................................................................................................... 376

19.2. Method set_value ..................................................................................................... 377

19.3. Method query .......................................................................................................... 382

19.4. Method start_query ................................................................................................... 384

19.5. Method run_query .................................................................................................... 385

19.6. Method reset_query .................................................................................................. 385

19.7. Method stop_query ................................................................................................... 386

19.8. Method comet ......................................................................................................... 388

19.9. Method get_schema .................................................................................................. 396

19.10. Method get_module_prefix_map ............................................................................... 397

19.11. Method run_action .................................................................................................. 399

19.12. Method login ......................................................................................................... 400

19.13. Method logout ....................................................................................................... 401

19.14. Method get_trans .................................................................................................... 403

19.15. Method new_trans .................................................................................................. 405

19.16. Method get_trans_changes ....................................................................................... 406

21.1. ConfD configuration for REST ................................................................................... 414

21.2. ConfD configuration of the authentication cache TTL ..................................................... 415

21.3. ConfD configuration of Client IP via Proxy .................................................................. 415

21.4. Request URI structure ............................................................................................... 416

21.5. Using curl for accessing ConfD .................................................................................. 417

21.6. Get the "sys/interfaces" resource represented as JSON .................................................... 418

21.7. Create a new "sys/routes/inet/route" resource, with JSON payload ..................................... 419

21.8. Replace the "sys/routes/inet/route" resource contents ...................................................... 420

21.9. Update the "sys/routes/inet/route" resource contents ....................................................... 421

21.10. Delete the "sys/routes/inet/route" resource contents ....................................................... 422

21.11. Get options for the "sys" resource ............................................................................. 422

21.12. Get head for the "sys/interfaces/ex:serial" resource ....................................................... 422

21.13. Shallow get for the "sys" resource ............................................................................. 424

21.14. Deep get for the "sys/interfaces/interface" resource ....................................................... 424

21.15. Limit the response .................................................................................................. 426

21.16. Limit the response with select .................................................................................. 426

21.17. The "sys/ntp/server" list (no defaults) ......................................................................... 427

21.18. The "sys/ntp/server" list with all defaults .................................................................... 428

21.19. Creating a "sys/routes/inet/route" resource .................................................................. 428

21.20. Creating a "sys/interfaces/serial/ppp0/multilink" resource ............................................... 429

21.21. Creating a "route" resource using PUT ....................................................................... 429

21.22. The "route" resource after creation ............................................................................ 430

21.23. Replacing a "route" resource using PUT ..................................................................... 430

21.24. The "route" resource after replace ............................................................................. 431

21.25. Creating a "sys/interfaces/serial/ppp0/multilink" resource ............................................... 431

21.26. Creating a "sys/interfaces/serial/ppp0/authentication" resource ........................................ 432

21.27. The "authentication" resource after replace .................................................................. 432

21.28. Updating a "route" resource using PATCH ................................................................. 433

21.29. The "route" resource after update .............................................................................. 433

21.30. Creating a "sys/interfaces/serial/ppp0/multilink" resource ............................................... 434

21.31. Creating a "sys/interfaces/serial/ppp0/authentication" resource ........................................ 434

21.32. The "authentication" resource after update .................................................................. 434

21.33. The "sys/dns/server" list before insert ........................................................................ 435

21.34. Insert=before in the "sys/dns/server" list ..................................................................... 435

xi

ConfD User Guide

21.35. The "sys/dns/server" list after insert ........................................................................... 436

21.36. An "archive-log" action request example .................................................................... 436

21.37. delete the "sys/interfaces/ex:serial" list ....................................................................... 438

21.38. The "sys/interfaces" resource after delete .................................................................... 438

21.39. delete the "sys/interfaces/ex:serial" list with rollback label and comment ........................... 438

21.40. Namespaces in JSON .............................................................................................. 440

21.41. GET the /api resource ............................................................................................. 442

21.42. GET the /api/running resource .................................................................................. 445

21.43. Action in /api/operational ......................................................................................... 445

21.44. GET rollback files information ................................................................................. 446

21.45. GET rollback file content ........................................................................................ 447

21.46. Find and use the rollback operation resource ............................................................... 448

21.47. XML representation of meta-data .............................................................................. 449

21.48. JSON representation of meta-data ............................................................................. 449

21.49. Example of a XML formatted error message ............................................................... 452

21.50. Example of a JSON formatted error message ............................................................... 452

21.51. ConfD configuration for REST ................................................................................. 459

21.52. ............................................................................................................................ 460

22.1. ConfD configuration for REST ................................................................................... 462

22.2. ConfD configuration for RESTCONF .......................................................................... 462

22.3. ConfD configuration of the authentication cache TTL ..................................................... 463

22.4. ConfD configuration of Client IP via Proxy .................................................................. 463

22.5. ConfD RESTCONF capabilities .................................................................................. 464

22.6. ConfD RESTCONF streams ....................................................................................... 464

22.7. ConfD RESTCONF errors during streaming ................................................................. 465

22.8. Use of collections .................................................................................................... 465

22.9. Use of collections .................................................................................................... 466

22.10. ConfD configuration for RESTCONF ........................................................................ 466

23.1. scli.yang YANG module ........................................................................................... 467

24.1. A data model divided into common and node specific subtrees ......................................... 475

25.1. Example snmpgw configuration fragment in confd.conf .................................................. 482

25.2. C code for registering reception of notifications ............................................................. 483

25.3. Example 1 of translating and compiling a MIB .............................................................. 484

26.1. smtp subagent data ................................................................................................... 487

26.2. imap and pop subagent data ....................................................................................... 487

26.3. Equipment subagent data ........................................................................................... 488

26.4. master agent data ..................................................................................................... 488

26.5. Compile the YANG modules at the master ................................................................... 488

26.6. Master agent's confd.conf .......................................................................................... 489

26.7. Proxy configuration .................................................................................................. 490

26.8. Agent replies with forward capability .......................................................................... 492

26.9. Manager issues forward rpc to board-1 ........................................................................ 492

26.10. Manager issues command ........................................................................................ 492

26.11. close-session .......................................................................................................... 493

26.12. Auto login ............................................................................................................. 493

26.13. Forward rpc with auth data ...................................................................................... 494

152. Reloading all xml files in the cdb directory ................................................................... 557

153. Merging in the contents of conf.cli ......................................................................... 557

154. Print interface config and statistics data in cli format ....................................................... 557

155. Using xslt to format output ......................................................................................... 557

156. Using xmllint to pretty print the xml output ................................................................... 557

157. Saving config and operational data to /tmp/conf.xml ................................................ 557

158. Restoring both config and operational data .................................................................... 557

159. Measure how long it takes to fetch config ..................................................................... 557

xii

ConfD User Guide

160. Output all instances in list /foo/table which has ix larger than 10 ............................... 557

161. confd-light.cli ........................................................................................................... 815

162. The servers YANG model ........................................................................................ 1009

xiii

Chapter 1. About the Documentation

1.1. How to Read This Guide

This document provides a wealth of information about ConfD and how to use it for your particular needs.

It is written to be useful both when read front-to-back and also for readers that need to dive into particular

aspects of the many features of ConfD.

Readers that are new to ConfD will learn a lot about how to think about, and apply, the features of ConfD

by reading the first twelve chapters of this guide. They give an overview of the foundations of ConfD and

how they can be used in various types of environments to meet various types of needs. Having read these

chapters will also be useful as a guide during early design decisions to avoid missing out on useful ConfD

features or applying features in a less than optimal way.

The rest of the document provides information about particular parts of ConfD. Time permitting, it is very

useful to read as a whole, but they may also be read selectively depending on which parts of ConfD you

are planning to use.

This document also consists of manual pages. The manual pages are reference information for the various

tools, libraries and configuration files that are included in the ConfD package. They can also be found in

native manual page format in the ConfD release package.

1.2. Getting Documentation

Updated documentation sets are prepared along with ConfD releases and can always be found in the

customer download area or as part of the various deliverables. All releases contains the following updated

documents:

• The ConfD User Guide is this document and is a separate download

• The CHANGES file describes all new features and corrections in the release and is a separate download

• The HIGHLIGHTS document is released with major releases and describes, with examples, all

substantial new features per release. The HIGHLIGHTS document is a separate download.

• The KNOWN_ISSUES file is part of the release package and documents all known open issues at the

time of release

• All ConfD release packages include a README file that describes how to install, set up and get started

with ConfD. The README file is located in the top directory of a ConfD installation.

• The example collection includes a README file that introduces the reader to the wide selection of

examples and what they contain. The README is contained in the examples deliverable.

All of the documents listed above contain information that is essential to the understanding of how to

extract the most value out of ConfD and we urge all our users to read them.

1.3. Formatting Conventions

We use the following text and syntax conventions throughout the documentation:

Operating system references (e.g. commands, environment variables, filenames and command options)

are rendered in fixed-width font

1

About the Documentation

Programming language constructs (e.g. functions, constants and error codes) are rendered in fixed-

width font

Multi-line code snippets and screen output are rendered like this:

# confdc -c test.cs

# confdc -l -o test.fxs test.xso

We use the following admonitions throughout this document:

Tip

This an example of a tip that is used to describe practical information on how to apply, or think

about a certain aspect of the product

Note

This is an example of a note that is used to highlight a particular piece of information

Warning

This is an example of a warning that points out information that needs particular attention to

avoid problems

1.4. Documentation Feedback

We appreciate documentation feedback, comments and suggestions so that we can continuously improve

the documentation and make it more useful. Use the request tracker system to send us your comments

and make sure you include information about which version and what section of the documentation you

are referring to.

2

Chapter 2. An introduction to ConfD

2.1. An on-device software system for

configuration management

Network devices, such as routers, switches or gateways, need to be configured and monitored. A fair

amount of software is embedded in these devices to facilitate configuration and monitoring. This software

typically includes:

• An SNMP agent for monitoring the device (SNMP is in practice almost never used for configuring

devices, although it is possible to do so).

• Software to drive and render a command line interface (CLI).

• A small web server and content making up a device-specific web site, for a web-based user interface

to the device management system.

In addition, the IETF has developed a standard called NETCONF for automated configuration of network

devices. NETCONF allows devices to expose an XML-based API that the network operator can use to set

and get full and partial configuration data sets.

NETCONF solves several management problems that have been lacking standardized solutions. However,

for an engineering organization with limited resources and a tight time schedule introducing/implementing

NETCONF also poses a problem; a whole new management sub-system needs to be implemented and

integrated with the other already existing management components, while time-to-market requirements

remain unchanged.

2.2. ConfD Architecture

Tail-f's ConfD is a device configuration toolkit meant to be integrated as a management sub-system in

network devices, providing:

• An implementation of the NETCONF protocol

• Automatic rendering of northbound interfaces, including CLI, Web UI and NETCONF

• Clustered/fault-tolerant storage of configuration data

• Master-agent/sub-agent framework for NETCONF, CLI, Web UI and SNMP

3

An introduction to ConfD

ConfD as sub-system on a network device

The following figure illustrates where ConfD would reside on, for example, a chassis-based router:

4

An introduction to ConfD

ConfD on a chassis-based router

ConfD executes as a regular Unix daemon on the target device, acting:

• as a NETCONF agent for the NETCONF protocol

• as a Web server for the Web UI

• as a CLI engine for command-line access

• and as an SNMP agent

It also contains a built-in XML configuration database.

The following figure illustrates the overall architecture. The ConfD architecture is modular, with well-

defined interfaces between sub-systems.

5

An introduction to ConfD

ConfD architecture

The NETCONF, SNMP, CLI and Web modules are Management Agents. These communicate with

external managers, and provide the managers with a protocol-specific view of the system. The box labeled

Other Agent is e.g. a GUI application or some other management protocol implementation. These other

Agents use the Management Agent API (MAAPI) to talk to the Management Backplane.

The Management Backplane provides an hierarchical view of the configuration and status/statistics data

through the Management Agent API. This API is a session-oriented read/write API to the hierarchical

data, with transaction-like semantics.

Examples of operations in this interface are 'create-subtree', 'get-instance', 'set-instance'. This interface is

used both when the configuration is stored in the built-in ConfD database, and when it is stored in an

external database.

The Management Backplane authenticates incoming requests through an AAA (Authentication,

Authorization, Accounting) plugin API. An AAA plugin authenticates users and authorizes their requests.

ConfD comes with a built-in AAA plugin, which can be replaced by vendor specific code.

In order to actually read and write the device-native configuration data, the sessions in the Management

Backplane use the Database Plugin API. A database plugin has to provide mapping from the hierarchical

view of the data used in the management protocols, to the native view used by the management database.

The management database can either be the integrated management database - called CDB - or some other

database. CDB is a light-weight fault-tolerant distributed XML database. CDB can be used in single or

multi-node systems in master slave configuration. It handles updates to the database schema automatically.

6

An introduction to ConfD

The Managed Objects in the application use the Managed Object API to read their configuration from the

ConfD management database. There is a also a subscription mechanism, which the Managed Objects can

use to react on configuration changes.

ConfD provides language bindings for the callback oriented plugin interfaces in C and Java. In the figure

above, the Database Plugin API and the AAA Plugin API are available in C and Java The normal function

call oriented APIs are available as C or Java APIs.

7

Page is loading ...

Software tail-f ConfD User guide

Software tail-f ConfD User guide

Related papers

Other documents