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