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