idnits 2.17.1 draft-ietf-netmod-syslog-model-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 08, 2017) is 2415 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC5425' is mentioned on line 359, but not defined == Unused Reference: 'RFC7895' is defined on line 1406, but no explicit reference was found in the text == Unused Reference: 'RFC6242' is defined on line 1435, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Downref: Normative reference to an Historic RFC: RFC 6587 ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD WG C. Wildes, Ed. 3 Internet-Draft Cisco Systems Inc. 4 Intended status: Standards Track K. Koushik, Ed. 5 Expires: March 12, 2018 Verizon Wireless 6 September 08, 2017 8 A YANG Data Model for Syslog Configuration 9 draft-ietf-netmod-syslog-model-17 11 Abstract 13 This document defines a YANG data model for the configuration of a 14 syslog process. It is intended this model be used by vendors who 15 implement syslog in their systems. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains many placeholder values that need to be replaced 20 with finalized values at the time of publication. This note 21 summarizes all of the substitutions that are needed. No other RFC 22 Editor instructions are specified elsewhere in this document. 24 Artwork in this document contains shorthand references to drafts in 25 progress. Please apply the following replacements: 27 o "xxxx" --> the assigned RFC value for draft-ietf-netconf-keystore 29 o "yyyy" --> the assigned RFC value for draft-ietf-netconf-tls- 30 client-server 32 o "zzzz" --> the assigned RFC value for this draft 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on March 12, 2018. 51 Copyright Notice 53 Copyright (c) 2017 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 69 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 70 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 4 72 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 4 73 3. Design of the Syslog Model . . . . . . . . . . . . . . . . . 5 74 3.1. Syslog Module . . . . . . . . . . . . . . . . . . . . . . 6 75 4. Syslog YANG Module . . . . . . . . . . . . . . . . . . . . . 8 76 4.1. The ietf-syslog Module . . . . . . . . . . . . . . . . . 8 77 5. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 26 78 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 28 79 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 80 7.1. The YANG Module Names Registry . . . . . . . . . . . . . 29 81 8. Security Considerations . . . . . . . . . . . . . . . . . . . 29 82 8.1. Resource Constraints . . . . . . . . . . . . . . . . . . 29 83 8.2. Inappropriate Configuration . . . . . . . . . . . . . . . 30 84 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 85 9.1. Normative References . . . . . . . . . . . . . . . . . . 30 86 9.2. Informative References . . . . . . . . . . . . . . . . . 31 87 Appendix A. Implementor Guidelines . . . . . . . . . . . . . . . 32 88 A.1. Extending Facilities . . . . . . . . . . . . . . . . . . 32 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 91 1. Introduction 93 Operating systems, processes and applications generate messages 94 indicating their own status or the occurrence of events. These 95 messages are useful for managing and/or debugging the network and its 96 services. The BSD syslog protocol is a widely adopted protocol that 97 is used for transmission and processing of the message. 99 Since each process, application and operating system was written 100 somewhat independently, there is little uniformity to the content of 101 syslog messages. For this reason, no assumption is made upon the 102 formatting or contents of the messages. The protocol is simply 103 designed to transport these event messages. No acknowledgement of 104 the receipt is made. 106 Essentially, a syslog process receives messages (from the kernel, 107 processes, applications or other syslog processes) and processes 108 them. The processing may involve logging to a local file, and/or 109 displaying on console, and/or relaying to syslog processes on other 110 machines. The processing is determined by the "facility" that 111 originated the message and the "severity" assigned to the message by 112 the facility. 114 We are using definitions of syslog protocol from [RFC5424] in this 115 RFC. 117 1.1. Requirements Language 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in [RFC2119] and 122 [RFC8174]. 124 1.2. Terminology 126 The term "originator" is defined in [RFC5424]: an "originator" 127 generates syslog content to be carried in a message. 129 The term "relay" is defined in [RFC5424]: a "relay" forwards 130 messages, accepting messages from originators or other relays and 131 sending them to collectors or other relays 133 The term "collectors" is defined in [RFC5424]: a "collector" gathers 134 syslog content for further analysis. 136 The term "action" refers to the processing that takes place for each 137 syslog message received. 139 1.3. Tree Diagrams 141 A simplified graphical representation of the data models is used in 142 this document. The meaning of the symbols in these diagrams is as 143 follows: 145 o Brackets "[" and "]" enclose list keys. 147 o Braces "{" and "}" enclose feature names, and indicate that the 148 named feature must be present for the subtree to be present. 150 o Abbreviations before data node names: "rw" means configuration 151 (read-write) and "ro" state data (read-only). 153 o Symbols after data node names: "?" means an optional node, "!" 154 means a presence container, and "*" denotes a list and leaf-list. 156 o Parentheses enclose choice and case nodes, and case nodes are also 157 marked with a colon (":"). 159 o Ellipsis ("...") stands for contents of subtrees that are not 160 shown. 162 2. Problem Statement 164 This document defines a YANG [RFC7950] configuration data model that 165 may be used to configure the syslog feature running on a system. 166 YANG models can be used with network management protocols such as 167 NETCONF [RFC6241] to install, manipulate, and delete the 168 configuration of network devices. 170 The data model makes use of the YANG "feature" construct which allows 171 implementations to support only those syslog features that lie within 172 their capabilities. 174 This module can be used to configure the syslog application 175 conceptual layers as implemented on the target system. 177 3. Design of the Syslog Model 179 The syslog model was designed by comparing various syslog features 180 implemented by various vendors' in different implementations. 182 This draft addresses the common leafs between implementations and 183 creates a common model, which can be augmented with proprietary 184 features, if necessary. This model is designed to be very simple for 185 maximum flexibility. 187 Some optional features are defined in this document to specify 188 functionality that is present in specific vendor configurations. 190 Syslog consists of originators and collectors. The following diagram 191 shows syslog messages flowing from an originator, to collectors where 192 filtering can take place. 194 Originators 195 +-------------+ +-------------+ +-------------+ +-------------+ 196 | Various | | OS | | | | Remote | 197 | Components | | Kernel | | Line Cards | | Servers | 198 +-------------+ +-------------+ +-------------+ +-------------+ 200 +-------------+ +-------------+ +-------------+ +-------------+ 201 | SNMP | | Interface | | Standby | | Syslog | 202 | Events | | Events | | Supervisor | | Itself | 203 +-------------+ +-------------+ +-------------+ +-------------+ 205 | | 206 +----------------------------------------------------------------+ 207 | 208 | 209 | 210 | 211 +-------------+--------------+ 212 | | | 213 v v v 214 Collectors 215 +----------+ +----------+ +----------------+ 216 | | | Log | |Remote Relay(s)/| 217 | Console | | File(s) | |Collector(s) | 218 +----------+ +----------+ +----------------+ 220 Figure 1. Syslog Processing Flow 222 Collectors are configured using the leaves in the syslog model 223 "actions" container which correspond to each message collector: 225 console 227 log file(s) 229 remote relay(s)/collector(s) 231 Within each action, a selector is used to filter syslog messages. A 232 selector consists of a list of one or more facility-severity matches, 233 and, if supported via the select-match feature, an optional regular 234 expression pattern match that is performed on the [RFC5424] field. 236 A syslog message is processed if: 238 There is an element of facility-list (F, S) where 239 the message facility matches F 240 and the message severity matches S 241 and/or the message text matches the regex pattern (if it is present) 243 The facility is one of a specific syslog-facility, or all facilities. 245 The severity is one of type syslog-severity, all severities, or none. 246 None is a special case that can be used to disable a filter. When 247 filtering severity, the default comparison is that messages of the 248 specified severity and higher are selected to be logged. This is 249 shown in the model as "default equals-or-higher". This behavior can 250 be altered if the select-adv-compare feature is enabled to specify a 251 compare operation and an action. Compare operations are: "equals" to 252 select messages with this single severity, or "equals-or-higher" to 253 select messages of the specified severity and higher. Actions are 254 used to log the message or block the message from being logged. 256 Many vendors extend the list of facilities available for logging in 257 their implementation. An example is included in Extending Facilities 258 (Appendix A.1). 260 3.1. Syslog Module 262 A simplified graphical representation of the data model is used in 263 this document. Please see Section 1.3 for tree diagram notation. 265 module: ietf-syslog 266 +--rw syslog! 267 +--rw actions 268 +--rw console! {console-action}? 269 | +--rw facility-filter 270 | | +--rw facility-list* [facility severity] 271 | | +--rw facility union 272 | | +--rw severity union 273 | | +--rw advanced-compare {select-adv-compare}? 274 | | +--rw compare? enumeration 275 | | +--rw action? enumeration 276 | +--rw pattern-match? string {select-match}? 277 +--rw file {file-action}? 278 | +--rw log-file* [name] 279 | +--rw name inet:uri 280 | +--rw facility-filter 281 | | +--rw facility-list* [facility severity] 282 | | +--rw facility union 283 | | +--rw severity union 284 | | +--rw advanced-compare {select-adv-compare}? 285 | | +--rw compare? enumeration 286 | | +--rw action? enumeration 287 | +--rw pattern-match? string {select-match}? 288 | +--rw structured-data? boolean {structured-data}? 289 | +--rw file-rotation 290 | +--rw number-of-files? uint32 {file-limit-size}? 291 | +--rw max-file-size? uint32 {file-limit-size}? 292 | +--rw rollover? uint32 293 | | {file-limit-duration}? 294 | +--rw retention? uint32 295 | {file-limit-duration}? 296 +--rw remote {remote-action}? 297 +--rw destination* [name] 298 +--rw name string 299 +--rw (transport) 300 | +--:(tcp) 301 | | +--rw tcp 302 | | +--rw address? inet:host 303 | | +--rw port? inet:port-number 304 | +--:(udp) 305 | | +--rw udp 306 | | +--rw address? inet:host 307 | | +--rw port? inet:port-number 308 | +--:(tls) 309 | +--rw tls 310 | +--rw address? inet:host 311 | +--rw port? inet:port-number 312 | +--rw server-auth 313 | | +--rw trusted-ca-certs? leafref 314 | | +--rw trusted-server-certs? leafref 315 | +--rw client-auth 316 | | +--rw (auth-type)? 317 | | +--:(certificate) 318 | | +--rw certificate? leafref 319 | +--rw hello-params 320 | {tls-client-hello-params-config}? 321 | +--rw tls-versions 322 | | +--rw tls-version* identityref 323 | +--rw cipher-suites 324 | +--rw cipher-suite* identityref 325 +--rw facility-filter 326 | +--rw facility-list* [facility severity] 327 | +--rw facility union 328 | +--rw severity union 329 | +--rw advanced-compare {select-adv-compare}? 330 | +--rw compare? enumeration 331 | +--rw action? enumeration 332 +--rw pattern-match? string {select-match}? 333 +--rw structured-data? boolean {structured-data}? 334 +--rw facility-override? identityref 335 +--rw source-interface? if:interface-ref 336 | {remote-source-interface}? 337 +--rw signing-options! {signed-messages}? 338 +--rw cert-signers 339 +--rw cert-signer* [name] 340 | +--rw name string 341 | +--rw certificate? leafref 342 | +--rw hash-algorithm? enumeration 343 +--rw cert-initial-repeat? uint32 344 +--rw cert-resend-delay? uint32 345 +--rw cert-resend-count? uint32 346 +--rw sig-max-delay? uint32 347 +--rw sig-number-resends? uint32 348 +--rw sig-resend-delay? uint32 349 +--rw sig-resend-count? uint32 351 Figure 2. ietf-syslog Module Tree 353 4. Syslog YANG Module 355 4.1. The ietf-syslog Module 357 This module imports typedefs from [RFC6021], [RFC7223], groupings 358 from [RFC yyyy], and [RFC xxxx], and it references [RFC5424], 359 [RFC5425], [RFC5426], [RFC6587], and [RFC5848]. 361 file "ietf-syslog.yang" 362 module ietf-syslog { 363 yang-version 1.1; 365 namespace "urn:ietf:params:xml:ns:yang:ietf-syslog"; 366 prefix syslog; 368 import ietf-inet-types { 369 prefix inet; 370 reference 371 "RFC 6991: INET Types Model"; 372 } 374 import ietf-interfaces { 375 prefix if; 376 reference 377 "RFC 7223: Interfaces Model"; 378 } 380 import ietf-tls-client { 381 prefix tlsc; 382 reference 383 "RFC xxxx: Keystore Model"; 384 } 386 import ietf-keystore { 387 prefix ks; 388 reference 389 "RFC yyyy: TLS Client and Server Models"; 390 } 392 organization "IETF 393 NETMOD (Network Modeling) Working Group"; 395 contact 396 "WG Web: 397 WG List: 399 Editor: Kiran Agrahara Sreenivasa 400 403 Editor: Clyde Wildes 404 "; 405 description 406 "This module contains a collection of YANG definitions 407 for syslog configuration. 409 Copyright (c) 2016 IETF Trust and the persons identified as 410 authors of the code. All rights reserved. 412 Redistribution and use in source and binary forms, with or 413 without modification, is permitted pursuant to, and subject to 414 the license terms contained in, the Simplified BSD License set 415 forth in Section 4.c of the IETF Trust's Legal Provisions 416 Relating to IETF Documents 417 (http://trustee.ietf.org/license-info). 419 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 420 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 421 'OPTIONAL' in the module text are to be interpreted as 422 described in RFC 2119 (http://tools.ietf.org/html/rfc2119). 424 This version of this YANG module is part of RFC zzzz 425 (http://tools.ietf.org/html/rfczzzz); see the RFC itself for 426 full legal notices."; 428 revision 2017-09-08 { 429 description 430 "Initial Revision"; 431 reference 432 "RFC zzzz: Syslog YANG Model"; 433 } 435 feature console-action { 436 description 437 "This feature indicates that the local console action is 438 supported."; 439 } 441 feature file-action { 442 description 443 "This feature indicates that the local file action is 444 supported."; 445 } 447 feature file-limit-size { 448 description 449 "This feature indicates that file logging resources 450 are managed using size and number limits."; 451 } 453 feature file-limit-duration { 454 description 455 "This feature indicates that file logging resources 456 are managed using time based limits."; 457 } 459 feature remote-action { 460 description 461 "This feature indicates that the remote server action is 462 supported."; 463 } 464 feature remote-source-interface { 465 description 466 "This feature indicates that source-interface is supported 467 supported for the remote-action."; 468 } 470 feature select-adv-compare { 471 description 472 "This feature represents the ability to select messages 473 using the additional comparison operators when comparing 474 the syslog message severity."; 475 } 477 feature select-match { 478 description 479 "This feature represents the ability to select messages 480 based on a Posix 1003.2 regular expression pattern match."; 481 } 483 feature structured-data { 484 description 485 "This feature represents the ability to log messages 486 in structured-data format as per RFC 5424."; 487 } 489 feature signed-messages { 490 description 491 "This feature represents the ability to configure signed 492 syslog messages according to RFC 5848."; 493 } 495 typedef syslog-severity { 496 type enumeration { 497 enum "emergency" { 498 value 0; 499 description 500 "The severity level 'Emergency' indicating that the 501 system is unusable."; 502 } 503 enum "alert" { 504 value 1; 505 description 506 "The severity level 'Alert' indicating that an action 507 must be taken immediately."; 508 } 509 enum "critical" { 510 value 2; 511 description 512 "The severity level 'Critical' indicating a critical 513 condition."; 514 } 515 enum "error" { 516 value 3; 517 description 518 "The severity level 'Error' indicating an error 519 condition."; 520 } 521 enum "warning" { 522 value 4; 523 description 524 "The severity level 'Warning' indicating a warning 525 condition."; 526 } 527 enum "notice" { 528 value 5; 529 description 530 "The severity level 'Notice' indicating a normal but 531 significant condition."; 532 } 533 enum "info" { 534 value 6; 535 description 536 "The severity level 'Info' indicating an informational 537 message."; 538 } 539 enum "debug" { 540 value 7; 541 description 542 "The severity level 'Debug' indicating a debug-level 543 message."; 544 } 545 } 546 description 547 "The definitions for Syslog message severity as per RFC 5424."; 548 } 550 identity syslog-facility { 551 description 552 "This identity is used as a base for all syslog facilities as 553 per RFC 5424."; 554 } 556 identity kern { 557 base syslog-facility; 558 description 559 "The facility for kernel messages (0) as defined in RFC 5424."; 561 } 563 identity user { 564 base syslog-facility; 565 description 566 "The facility for user-level messages (1) as defined in 567 RFC 5424."; 568 } 570 identity mail { 571 base syslog-facility; 572 description 573 "The facility for the mail system (2) as defined in RFC 5424."; 574 } 576 identity daemon { 577 base syslog-facility; 578 description 579 "The facility for the system daemons (3) as defined in 580 RFC 5424."; 581 } 583 identity auth { 584 base syslog-facility; 585 description 586 "The facility for security/authorization messages (4) as 587 defined in RFC 5424."; 588 } 590 identity syslog { 591 base syslog-facility; 592 description 593 "The facility for messages generated internally by syslogd 594 facility (5) as defined in RFC 5424."; 595 } 597 identity lpr { 598 base syslog-facility; 599 description 600 "The facility for the line printer subsystem (6) as defined 601 in RFC 5424."; 602 } 604 identity news { 605 base syslog-facility; 606 description 607 "The facility for the network news subsystem (7) as defined 608 in RFC 5424."; 610 } 612 identity uucp { 613 base syslog-facility; 614 description 615 "The facility for the UUCP subsystem (8) as defined in 616 RFC 5424."; 617 } 619 identity cron { 620 base syslog-facility; 621 description 622 "The facility for the clock daemon (9) as defined in 623 RFC 5424."; 624 } 626 identity authpriv { 627 base syslog-facility; 628 description 629 "The facility for privileged security/authorization messages 630 (10) as defined in RFC 5424."; 631 } 633 identity ftp { 634 base syslog-facility; 635 description 636 "The facility for the FTP daemon (11) as defined in RFC 5424."; 637 } 639 identity ntp { 640 base syslog-facility; 641 description 642 "The facility for the NTP subsystem (12) as defined in 643 RFC 5424."; 644 } 646 identity audit { 647 base syslog-facility; 648 description 649 "The facility for log audit messages (13) as defined in 650 RFC 5424."; 651 } 653 identity console { 654 base syslog-facility; 655 description 656 "The facility for log alert messages (14) as defined in 657 RFC 5424."; 659 } 661 identity cron2 { 662 base syslog-facility; 663 description 664 "The facility for the second clock daemon (15) as defined in 665 RFC 5424."; 666 } 668 identity local0 { 669 base syslog-facility; 670 description 671 "The facility for local use 0 messages (16) as defined in 672 RFC 5424."; 673 } 675 identity local1 { 676 base syslog-facility; 677 description 678 "The facility for local use 1 messages (17) as defined in 679 RFC 5424."; 680 } 682 identity local2 { 683 base syslog-facility; 684 description 685 "The facility for local use 2 messages (18) as defined in 686 RFC 5424."; 687 } 689 identity local3 { 690 base syslog-facility; 691 description 692 "The facility for local use 3 messages (19) as defined in 693 RFC 5424."; 694 } 696 identity local4 { 697 base syslog-facility; 698 description 699 "The facility for local use 4 messages (20) as defined in 700 RFC 5424."; 701 } 703 identity local5 { 704 base syslog-facility; 705 description 706 "The facility for local use 5 messages (21) as defined in 707 RFC 5424."; 708 } 710 identity local6 { 711 base syslog-facility; 712 description 713 "The facility for local use 6 messages (22) as defined in 714 RFC 5424."; 715 } 717 identity local7 { 718 base syslog-facility; 719 description 720 "The facility for local use 7 messages (23) as defined in 721 RFC 5424."; 722 } 724 grouping severity-filter { 725 description 726 "This grouping defines the processing used to select 727 log messages by comparing syslog message severity using 728 the following processing rules: 729 - if 'none', do not match. 730 - if 'all', match. 731 - else compare message severity with the specified severity 732 according to the default compare rule (all messages of the 733 specified severity and greater match) or if the 734 select-adv-compare feature is present, the advance-compare 735 rule."; 736 leaf severity { 737 type union { 738 type syslog-severity; 739 type enumeration { 740 enum none { 741 value 2147483647; 742 description 743 "This enum describes the case where no severities 744 are selected."; 745 } 746 enum all { 747 value -2147483648; 748 description 749 "This enum describes the case where all severities 750 are selected."; 751 } 752 } 753 } 754 mandatory true; 755 description 756 "This leaf specifies the syslog message severity."; 757 } 758 container advanced-compare { 759 when '../severity != "all" and 760 ../severity != "none"' { 761 description 762 "The advanced compare container is not applicable for 763 severity 'all' or severity 'none'"; 764 } 765 if-feature select-adv-compare; 766 leaf compare { 767 type enumeration { 768 enum equals { 769 description 770 "This enum specifies that the severity comparison 771 operation will be equals."; 772 } 773 enum equals-or-higher { 774 description 775 "This enum specifies that the severity comparison 776 operation will be equals or higher."; 777 } 778 } 779 default equals-or-higher; 780 description 781 "The compare can be used to specify the comparison 782 operator that should be used to compare the syslog message 783 severity with the specified severity."; 784 } 785 leaf action { 786 type enumeration { 787 enum log { 788 description 789 "This enum specifies that if the compare operation is 790 true the message will be logged."; 791 } 792 enum block { 793 description 794 "This enum specifies that if the compare operation is 795 true the message will not be logged."; 796 } 797 } 798 default log; 799 description 800 "The action can be used to spectify if the message should 801 be logged or blocked based on the outcome of the compare 802 operation."; 804 } 805 description 806 "This container describes additional severity compare 807 operations that can be used in place of the default 808 severity comparison. The compare leaf specifies the type of 809 the compare that is done and the action leaf specifies the 810 intended result. 811 Example: compare->equals and action->no-match means 812 messages that have a severity that is not equal to the 813 specified severity will be logged."; 814 } 815 } 817 grouping selector { 818 description 819 "This grouping defines a syslog selector which is used to 820 select log messages for the log-actions (console, file, 821 remote, etc.). Choose one or both of the following: 822 facility [ ...] 823 pattern-match regular-expression-match-string 824 If both facility and pattern-match are specified, both must 825 match in order for a log message to be selected."; 826 container facility-filter { 827 description 828 "This container describes the syslog filter parameters."; 829 list facility-list { 830 key "facility severity"; 831 ordered-by user; 832 description 833 "This list describes a collection of syslog 834 facilities and severities."; 835 leaf facility { 836 type union { 837 type identityref { 838 base syslog-facility; 839 } 840 type enumeration { 841 enum all { 842 description 843 "This enum describes the case where all 844 facilities are requested."; 845 } 846 } 847 } 848 description 849 "The leaf uniquely identifies a syslog facility."; 850 } 851 uses severity-filter; 853 } 854 } 855 leaf pattern-match { 856 if-feature select-match; 857 type string; 858 description 859 "This leaf describes a Posix 1003.2 regular expression 860 string that can be used to select a syslog message for 861 logging. The match is performed on the RFC 5424 862 SYSLOG-MSG field."; 863 } 864 } 866 grouping structured-data { 867 description 868 "This grouping defines the syslog structured data option 869 which is used to select the format used to write log 870 messages."; 871 leaf structured-data { 872 if-feature structured-data; 873 type boolean; 874 default false; 875 description 876 "This leaf describes how log messages are written. 877 If true, messages will be written with one or more 878 STRUCTURED-DATA elements as per RFC 5424; if false, 879 messages will be written with STRUCTURED-DATA = 880 NILVALUE."; 881 } 882 } 884 container syslog { 885 presence "Enables logging."; 886 description 887 "This container describes the configuration parameters for 888 syslog."; 889 container actions { 890 description 891 "This container describes the log-action parameters 892 for syslog."; 893 container console { 894 if-feature console-action; 895 presence "Enables logging to the console"; 896 description 897 "This container describes the configuration parameters 898 for console logging."; 899 uses selector; 900 } 901 container file { 902 if-feature file-action; 903 description 904 "This container describes the configuration parameters for 905 file logging. If file-archive limits are not supplied, it 906 is assumed that the local implementation defined limits 907 will be used."; 908 list log-file { 909 key "name"; 910 description 911 "This list describes a collection of local logging 912 files."; 913 leaf name { 914 type inet:uri { 915 pattern 'file:.*'; 916 } 917 description 918 "This leaf specifies the name of the log file which 919 MUST use the uri scheme file:."; 920 } 921 uses selector; 922 uses structured-data; 923 container file-rotation { 924 description 925 "This container describes the configuration 926 parameters for log file rotation."; 927 leaf number-of-files { 928 if-feature file-limit-size; 929 type uint32; 930 default 1; 931 description 932 "This leaf specifies the maximum number of log 933 files retained. Specify 1 for implementations 934 that only support one log file."; 935 } 936 leaf max-file-size { 937 if-feature file-limit-size; 938 type uint32; 939 units "megabytes"; 940 description 941 "This leaf specifies the maximum log file size."; 942 } 943 leaf rollover { 944 if-feature file-limit-duration; 945 type uint32; 946 units "minutes"; 947 description 948 "This leaf specifies the length of time that log 949 events should be written to a specific log file. 950 Log events that arrive after the rollover period 951 cause the current log file to be closed and a new 952 log file to be opened."; 953 } 954 leaf retention { 955 if-feature file-limit-duration; 956 type uint32; 957 units "hours"; 958 description 959 "This leaf specifies the length of time that 960 completed/closed log event files should be stored 961 in the file system before they are deleted."; 962 } 963 } 964 } 965 } 966 container remote { 967 if-feature remote-action; 968 description 969 "This container describes the configuration parameters 970 for forwarding syslog messages to remote relays or 971 collectors."; 972 list destination { 973 key "name"; 974 description 975 "This list describes a collection of remote logging 976 destinations."; 977 leaf name { 978 type string; 979 description 980 "An arbitrary name for the endpoint to connect to."; 981 } 982 choice transport { 983 mandatory true; 984 description 985 "This choice describes the transport option."; 986 case tcp { 987 container tcp { 988 description 989 "This container describes the TCP transport 990 options."; 991 reference 992 "RFC 6587: Transmission of Syslog Messages over 993 TCP"; 994 leaf address { 995 type inet:host; 996 description 997 "The leaf uniquely specifies the address of 998 the remote host. One of the following must 999 be specified: an ipv4 address, an ipv6 1000 address, or a host name."; 1001 } 1002 leaf port { 1003 type inet:port-number; 1004 default 514; 1005 description 1006 "This leaf specifies the port number used to 1007 deliver messages to the remote server."; 1008 } 1009 } 1010 } 1011 case udp { 1012 container udp { 1013 description 1014 "This container describes the UDP transport 1015 options."; 1016 reference 1017 "RFC 5426: Transmission of Syslog Messages over 1018 UDP"; 1019 leaf address { 1020 type inet:host; 1021 description 1022 "The leaf uniquely specifies the address of 1023 the remote host. One of the following must be 1024 specified: an ipv4 address, an ipv6 address, 1025 or a host name."; 1026 } 1027 leaf port { 1028 type inet:port-number; 1029 default 514; 1030 description 1031 "This leaf specifies the port number used to 1032 deliver messages to the remote server."; 1033 } 1034 } 1035 } 1036 case tls { 1037 container tls { 1038 description 1039 "This container describes the TLS transport 1040 options."; 1041 reference 1042 "RFC 5425: Transport Layer Security (TLS) 1043 Transport Mapping for Syslog "; 1044 leaf address { 1045 type inet:host; 1046 description 1047 "The leaf uniquely specifies the address of 1048 the remote host. One of the following must be 1049 specified: an ipv4 address, an ipv6 address, 1050 or a host name."; 1051 } 1052 leaf port { 1053 type inet:port-number; 1054 default 6514; 1055 description 1056 "TCP port 6514 has been allocated as the default 1057 port for syslog over TLS."; 1058 } 1059 uses tlsc:tls-client-grouping; 1060 } 1061 } 1062 } 1063 uses selector; 1064 uses structured-data; 1065 leaf facility-override { 1066 type identityref { 1067 base syslog-facility; 1068 } 1069 description 1070 "If specified, this leaf specifies the facility used 1071 to override the facility in messages delivered to 1072 the remote server."; 1073 } 1074 leaf source-interface { 1075 if-feature remote-source-interface; 1076 type if:interface-ref; 1077 description 1078 "This leaf sets the source interface to be used to 1079 send messages to the remote syslog server. If not 1080 set, messages sent to a remote syslog server will 1081 contain the IP address of the interface the syslog 1082 message uses to exit the network element"; 1083 } 1084 container signing-options { 1085 if-feature signed-messages; 1086 presence 1087 "If present, syslog-signing options is activated."; 1088 description 1089 "This container describes the configuration 1090 parameters for signed syslog messages as described 1091 by RFC 5848."; 1092 reference 1093 "RFC 5848: Signed Syslog Messages"; 1094 container cert-signers { 1095 description 1096 "This container describes the signing certificate 1097 configuration for Signature Group 0 which covers 1098 the case for administrators who want all Signature 1099 Blocks to be sent to a single destination."; 1100 list cert-signer { 1101 key "name"; 1102 description 1103 "This list describes a collection of syslog 1104 message signers."; 1105 leaf name { 1106 type string; 1107 description 1108 "This leaf specifies the name of the syslog 1109 message signer."; 1110 } 1111 leaf certificate { 1112 type leafref { 1113 path "/ks:keystore/ks:keys/ks:key/ks:certificates" 1114 + "/ks:certificate/ks:name"; 1115 } 1116 description 1117 "This is the certificate that is periodically 1118 sent to the remote receiver. Selection of the 1119 certificate also implicitly selects the private 1120 key used to sign the syslog messages."; 1121 } 1122 leaf hash-algorithm { 1123 type enumeration { 1124 enum SHA1 { 1125 value 1; 1126 description 1127 "This enum describes the SHA1 algorithm."; 1128 } 1129 enum SHA256 { 1130 value 2; 1131 description 1132 "This enum describes the SHA256 algorithm."; 1133 } 1134 } 1135 description 1136 "This leaf describes the syslog signer hash 1137 algorithm used."; 1138 } 1139 } 1140 leaf cert-initial-repeat { 1141 type uint32; 1142 default 3; 1143 description 1144 "This leaf specifies the number of times each 1145 Certificate Block should be sent before the first 1146 message is sent."; 1147 } 1148 leaf cert-resend-delay { 1149 type uint32; 1150 units "seconds"; 1151 default 3600; 1152 description 1153 "This leaf specifies the maximum time delay in 1154 seconds until resending the Certificate Block."; 1155 } 1156 leaf cert-resend-count { 1157 type uint32; 1158 default 0; 1159 description 1160 "This leaf specifies the maximum number of other 1161 syslog messages to send until resending the 1162 Certificate Block."; 1163 } 1164 leaf sig-max-delay { 1165 type uint32; 1166 units "seconds"; 1167 default 60; 1168 description 1169 "This leaf specifies when to generate a new 1170 Signature Block. If this many seconds have 1171 elapsed since the message with the first message 1172 number of the Signature Block was sent, a new 1173 Signature Block should be generated."; 1174 } 1175 leaf sig-number-resends { 1176 type uint32; 1177 default 0; 1178 description 1179 "This leaf specifies the number of times a 1180 Signature Block is resent. (It is recommended to 1181 select a value of greater than 0 in particular 1182 when the UDP transport RFC 5426 is used.)."; 1183 } 1184 leaf sig-resend-delay { 1185 type uint32; 1186 units "seconds"; 1187 default 5; 1188 description 1189 "This leaf specifies when to send the next 1190 Signature Block transmission based on time. If 1191 this many seconds have elapsed since the previous 1192 sending of this Signature Block, resend it."; 1193 } 1194 leaf sig-resend-count { 1195 type uint32; 1196 default 0; 1197 description 1198 "This leaf specifies when to send the next 1199 Signature Block transmission based on a count. 1200 If this many other syslog messages have been 1201 sent since the previous sending of this 1202 Signature Block, resend it. A value of 0 means 1203 that you don't resend based on the number of 1204 messages."; 1205 } 1206 } 1207 } 1208 } 1209 } 1210 } 1211 } 1212 } 1213 1215 Figure 3. ietf-syslog Module 1217 5. Usage Examples 1218 Requirement: 1219 Enable console logging of syslogs of severity critical 1221 Here is the example syslog configuration xml: 1222 1223 1225 1226 1227 1228 1229 all 1230 critical 1231 1232 1233 1234 1235 1236 1238 Enable remote logging of syslogs to udp destination 2001:db8:a0b:12f0::1 1239 for facility auth, severity error 1241 1242 1244 1245 1246 1247 remote1 1248 1249
2001:db8:a0b:12f0::1
1250 1251 1252 1253 auth 1254 error 1255 1256 1257 1258 1259 1260 1261 1263 Figure 4. ietf-syslog Examples 1265 6. Acknowledgements 1267 The authors wish to thank the following who commented on this 1268 proposal: 1270 Andy Bierman 1272 Martin Bjorklund 1274 Alex Campbell 1276 Alex Clemm 1278 Jim Gibson 1280 Jeffrey Haas 1282 John Heasley 1284 Giles Heron 1286 Lisa Huang 1288 Mahesh Jethanandani 1290 Jeffrey K Lange 1292 Jan Lindblad 1294 Chris Lonvick 1296 Tom Petch 1298 Juergen Schoenwaelder 1300 Phil Shafer 1302 Jason Sterne 1304 Peter Van Horne 1306 Kent Watsen 1308 Bert Wijnen 1310 Dale R Worley 1312 Aleksandr Zhdankin 1314 7. IANA Considerations 1316 This document registers one URI in the IETF XML registry [RFC3688]. 1317 Following the format in [RFC3688], the following registration is 1318 requested: 1320 URI: urn:ietf:params:xml:ns:yang:ietf-syslog 1321 Registrant Contact: The NETCONF WG of the IETF. 1322 XML: N/A, the requested URI is an XML namespace. 1324 7.1. The YANG Module Names Registry 1326 This document registers one YANG module in the YANG Module Names 1327 registry [RFC7895]/>. Following the format in [RFC7950]/>, the the 1328 following registration is requested: 1330 name: ietf-syslog 1331 namespace: urn:ietf:params:xml:ns:yang:ietf-syslog 1332 prefix: ietf-syslog 1333 reference: RFC zzzz 1335 8. Security Considerations 1337 The YANG module defined in this document is designed to be accessed 1338 via YANG based management protocols, such as NETCONF [RFC6241] and 1339 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1340 implement secure transport layers (e.g., SSH, TLS) with mutual 1341 authentication. 1343 The NETCONF access control model (NACM) [RFC6536] provides the means 1344 to restrict access for particular users to a pre-configured subset of 1345 all available protocol operations and content. 1347 There are a number of data nodes defined in this YANG module that are 1348 writable/creatable/deletable (i.e., config true, which is the 1349 default). These data nodes may be considered sensitive or vulnerable 1350 in some network environments. Write operations (e.g., edit-config) 1351 to these data nodes without proper protection can have a negative 1352 effect on network operations. 1354 8.1. Resource Constraints 1356 It is the responsibility of the network administrator to ensure that 1357 the configured message flow does not overwhelm system resources. 1359 Network administrators must take the time to estimate the appropriate 1360 storage capacity caused by the configuration of actions/file using 1361 file-archive attributes to limit storage used. 1363 8.2. Inappropriate Configuration 1365 It is the responsibility of the network administrator to ensure that 1366 the messages are actually going to the intended recipients. 1368 9. References 1370 9.1. Normative References 1372 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1373 Requirement Levels", BCP 14, RFC 2119, 1374 DOI 10.17487/RFC2119, March 1997, 1375 . 1377 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, 1378 DOI 10.17487/RFC5424, March 2009, 1379 . 1381 [RFC5426] Okmianski, A., "Transmission of Syslog Messages over UDP", 1382 RFC 5426, DOI 10.17487/RFC5426, March 2009, 1383 . 1385 [RFC5848] Kelsey, J., Callas, J., and A. Clemm, "Signed Syslog 1386 Messages", RFC 5848, DOI 10.17487/RFC5848, May 2010, 1387 . 1389 [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", 1390 RFC 6021, DOI 10.17487/RFC6021, October 2010, 1391 . 1393 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1394 Protocol (NETCONF) Access Control Model", RFC 6536, 1395 DOI 10.17487/RFC6536, March 2012, 1396 . 1398 [RFC6587] Gerhards, R. and C. Lonvick, "Transmission of Syslog 1399 Messages over TCP", RFC 6587, DOI 10.17487/RFC6587, April 1400 2012, . 1402 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1403 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1404 . 1406 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1407 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1408 . 1410 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1411 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1412 . 1414 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1415 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1416 May 2017, . 1418 [Std-1003.1-2008] 1419 The Open Group, ""Chapter 9: Regular Expressions". The 1420 Open Group Base Specifications Issue 6, IEEE Std 1421 1003.1-2008, 2016 Edition.", September 2016, 1422 . 1424 9.2. Informative References 1426 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1427 DOI 10.17487/RFC3688, January 2004, 1428 . 1430 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1431 and A. Bierman, Ed., "Network Configuration Protocol 1432 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1433 . 1435 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1436 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1437 . 1439 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1440 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1441 . 1443 Appendix A. Implementor Guidelines 1445 A.1. Extending Facilities 1447 Many vendors extend the list of facilities available for logging in 1448 their implementation. Additional facilities may not work with the 1449 syslog protocol as defined in [RFC5424] and hence such facilities 1450 apply for local syslog-like logging functionality. 1452 The following is an example that shows how additional facilities 1453 could be added to the list of available facilities (in this example 1454 two facilities are added): 1456 module vendor-syslog-types-example { 1457 namespace "urn:vendor:params:xml:ns:yang:vendor-syslog-types"; 1458 prefix vendor-syslogtypes; 1460 import ietf-syslog { 1461 prefix syslogtypes; 1462 } 1464 organization "Example, Inc."; 1465 contact 1466 "Example, Inc. 1467 Customer Service 1469 E-mail: syslog-yang@example.com"; 1471 description 1472 "This module contains a collection of vendor-specific YANG type 1473 definitions for SYSLOG."; 1475 revision 2017-08-11 { 1476 description 1477 "Version 1.0"; 1478 reference 1479 "Vendor SYSLOG Types: SYSLOG YANG Model"; 1480 } 1482 identity vendor_specific_type_1 { 1483 base syslogtypes:syslog-facility; 1484 } 1486 identity vendor_specific_type_2 { 1487 base syslogtypes:syslog-facility; 1488 } 1489 } 1491 Authors' Addresses 1493 Clyde Wildes (editor) 1494 Cisco Systems Inc. 1495 170 West Tasman Drive 1496 San Jose, CA 95134 1497 US 1499 Phone: +1 408 527-2672 1500 EMail: cwildes@cisco.com 1502 Kiran Koushik (editor) 1503 Verizon Wireless 1504 500 W Dove Rd. 1505 Southlake, TX 76092 1506 US 1508 Phone: +1 512 650-0210 1509 EMail: kirankoushik.agraharasreenivasa@verizonwireless.com