idnits 2.17.1 draft-ietf-netmod-syslog-model-12.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 38 instances of too long lines in the document, the longest one being 16 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 202 has weird spacing: '...eratorn and a...' == Line 224 has weird spacing: '... rw for c...' == Line 225 has weird spacing: '... ro for n...' == Line 304 has weird spacing: '...-repeat uin...' -- The document date (February 14, 2017) is 2628 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 598, but not defined == Missing Reference: 'RFC6536' is mentioned on line 1262, 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: 5 errors (**), 0 flaws (~~), 8 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 K. Koushik, Ed. 4 Intended status: Standards Track Cisco Systems Inc. 5 Expires: August 16, 2017 February 14, 2017 7 A YANG Data Model for Syslog Configuration 8 draft-ietf-netmod-syslog-model-12 10 Abstract 12 This document describes a data model for the configuration of syslog. 14 Status of this Memo 16 This Internet-Draft is submitted in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF). Note that other groups may also distribute 21 working documents as Internet-Drafts. The list of current Internet- 22 Drafts is at http://datatracker.ietf.org/drafts/current/. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 This Internet-Draft will expire on August 16, 2017. 31 Copyright Notice 33 Copyright (c) 2017 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 38 license-info) in effect on the date of publication of this document. 39 Please review these documents carefully, as they describe your rights 40 and restrictions with respect to this document. Code Components 41 extracted from this document must include Simplified BSD License text 42 as described in Section 4.e of the Trust Legal Provisions and are 43 provided without warranty as described in the Simplified BSD License. 45 Table of Contents 47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 48 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2 49 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 50 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 2 51 3. Design of the Syslog Model . . . . . . . . . . . . . . . . . . 3 52 3.1. Syslog Module . . . . . . . . . . . . . . . . . . . . . . 5 53 4. Syslog YANG Modules . . . . . . . . . . . . . . . . . . . . . 8 54 4.1. The ietf-syslog-types Module . . . . . . . . . . . . . . . 8 55 4.2. The ietf-syslog Module . . . . . . . . . . . . . . . . . . 14 56 5. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . 25 57 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 26 58 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 59 8. Security Considerations . . . . . . . . . . . . . . . . . . . 27 60 8.1. Resource Constraints . . . . . . . . . . . . . . . . . . . 27 61 8.2. Inappropriate Configuration . . . . . . . . . . . . . . . 27 62 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 63 9.1. Normative References . . . . . . . . . . . . . . . . . . . 27 64 9.2. Informative References . . . . . . . . . . . . . . . . . . 28 65 Appendix A. Implementor Guidelines . . . . . . . . . . . . . . . . 28 66 Appendix A.1. Extending Facilities . . . . . . . . . . . . . . 28 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 69 1. Introduction 71 Operating systems, processes and applications generate messages 72 indicating their own status or the occurrence of events. These 73 messages are useful for managing and/or debugging the network and its 74 services. The BSD syslog protocol is a widely adopted protocol that 75 is used for transmission and processing of the messages. 77 Since each process, application and operating system was written 78 somewhat independently, there is little uniformity to the content of 79 syslog messages. For this reason, no assumption is made upon the 80 formatting or contents of the messages. The protocol is simply 81 designed to transport these event messages. No acknowledgement of 82 the receipt is made. 84 Essentially, a syslog process receives messages (from the kernel, 85 processes, applications or other syslog processes) and processes 86 those. The processing involves logging to a local file, displaying 87 on console, and/or relaying to syslog processes on other machines. 88 The processing is determined by the "facility" that originated the 89 message and the "severity" assigned to the message by the facility. 91 We are using definitions of syslog protocol from [RFC5424] in this 92 RFC. 94 1.1. Requirements Language 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 98 document are to be interpreted as described in RFC 2119 [RFC2119]. 100 1.2. Terminology 102 The term "originator" is defined in [RFC5424]: an "originator" 103 generates syslog content to be carried in a message. 105 The terms "relay" and "collectors" are as defined in [RFC5424]. 107 2. Problem Statement 108 This document defines a YANG [RFC6020] configuration data model that 109 may be used to configure the syslog feature running on a system. 110 YANG models can be used with network management protocols such as 111 NETCONF [RFC6241] to install, manipulate, and delete the 112 configuration of network devices. 114 The data model makes use of the YANG "feature" construct which allows 115 implementations to support only those syslog features that lie within 116 their capabilities. 118 This module can be used to configure the syslog application 119 conceptual layers as implemented on the target system [RFC5424]. 121 3. Design of the Syslog Model 123 The syslog model was designed by comparing various syslog features 124 implemented by various vendors' in different implementations. 126 This draft addresses the common leafs between implementations and 127 creates a common model, which can be augmented with proprietary 128 features, if necessary. The base model is designed to be very simple 129 for maximum flexibility. 131 Optional features are used to specify functionality that is present 132 in specific vendor configurations. 134 Syslog consists of originators, and collectors. The following 135 diagram shows syslog messages flowing from an originator, to 136 collectors where filtering can take place. 138 Many vendors extend the list of facilities available for logging in 139 their implementation. An example is included in Extending Facilities 140 (Appendix A.1). 142 Originators 143 +-------------+ +-------------+ +-------------+ +-------------+ 144 | Various | | OS | | | | Remote | 145 | Components | | Kernel | | Line Cards | | Servers | 146 +-------------+ +-------------+ +-------------+ +-------------+ 148 +-------------+ +-------------+ +-------------+ +-------------+ 149 | SNMP | | Interface | | Standby | | Syslog | 150 | Events | | Events | | Supervisor | | Itself | 151 +-------------+ +-------------+ +-------------+ +-------------+ 153 | | 154 +----------------------------------------------------------------+ 155 | 156 | 157 | 158 | 159 +-------------+--------------+ 160 | | | 161 v v v 162 Collectors 163 +----------+ +----------+ +----------------+ 164 | | | Log | |Remote Relay(s)/| 165 | Console | | File(s) | |Collector(s) | 166 +----------+ +----------+ +----------------+ 168 Figure 1. Syslog Processing Flow 170 The leaves in the base syslog model actions container correspond to 171 each message collector: 173 console 174 log file(s) 175 remote relay(s)/collector(s) 177 Within each action, a selector is used to filter syslog messages. A 178 selector consists of a list of one or more facility-severity matches, 179 and, if supported via the select-match feature, an optional regular 180 expression pattern match that is performed on the SYSLOG-MSG field. 182 Selector processing (input is syslog message): 184 1. Loop through facility-list 185 a. Facility match processing - continue to the next entry in 186 the list if no match 187 b. Severity compare processing - continue to the next list 188 entry if no match 189 c. Match - proceed with the action and exit further processing 190 2. Process pattern match if specified and if a match proceed with 191 the action 193 The facility is one of a specific syslogtypes:syslog-facility, or all 194 facilities. 196 The severity is one of syslogtypes:severity, all severities, or none. 197 None is a special case that can be used to disable a facility. When 198 filtering severity, the default comparison is that messages of the 199 specified severity and higher are selected to be logged. This is 200 shown in the model as "default equals-or-higher". This behavior can 201 be altered if the select-adv-compare feature is enabled to specify a 202 compare operatorn and an action. Compare operations are: "equals" 203 to select messages with this single severity, or "equals-or-higher" 204 to select messages of the specified severity and higher. Actions are 205 to log the message or block the message from being logged. 207 3.1. Syslog Module 209 A simplified graphical representation of the complete data tree is 210 presented here. 212 Each node is printed as: 214 216 is one of: 218 + for current 219 x for deprecated 220 o for obsolete 222 is one of: 224 rw for configuration data 225 ro for non-configuration data 226 -x for rpcs 227 -n for notifications 229 is the name of the node 231 () means that the node is a choice node 232 :() means that the node is a case node 234 If the node is augmented into the tree from another module, its name 235 is printed as :. 237 is one of: 239 ? for an optional leaf or choice 240 ! for a presence container 241 * for a leaf-list or list 242 [] for a list's keys 244 is the name of the type for leafs and leaf-lists 246 If the type is a leafref, the type is printed as "-> TARGET", where 247 TARGET is either the leafref path, with prefixed removed if possible. 249 is the list of features this node depends on, printed 250 within curly brackets and a question mark "{...}?" 251 module: ietf-syslog 252 +--rw syslog! 253 +--rw actions 254 +--rw console! {console-action}? 255 | +--rw selector 256 | +--rw facility-list* [facility severity] 257 | | +--rw facility union 258 | | +--rw severity union 259 | | +--rw advanced-compare {select-adv-compare}? 260 | | +--rw compare? enumeration 261 | | +--rw action? enumeration 262 | +--rw pattern-match? string {select-match}? 263 +--rw file {file-action}? 264 | +--rw log-file* [name] 265 | +--rw name inet:uri 266 | +--rw selector 267 | | +--rw facility-list* [facility severity] 268 | | | +--rw facility union 269 | | | +--rw severity union 270 | | | +--rw advanced-compare {select-adv-compare}? 271 | | | +--rw compare? enumeration 272 | | | +--rw action? enumeration 273 | | +--rw pattern-match? string {select-match}? 274 | +--rw structured-data? boolean {structured-data}? 275 | +--rw file-rotation 276 | +--rw number-of-files? uint32 {file-limit-size}? 277 | +--rw max-file-size? uint32 {file-limit-size}? 278 | +--rw rollover? uint32 {file-limit-duration}? 279 | +--rw retention? uint32 {file-limit-duration}? 280 +--rw remote {remote-action}? 281 +--rw destination* [name] 282 +--rw name string 283 +--rw (transport) 284 | +--:(tcp) 285 | | +--rw tcp 286 | | +--rw address? inet:host 287 | | +--rw port? inet:port-number 288 | +--:(udp) 289 | +--rw udp 290 | +--rw address? inet:host 291 | +--rw port? inet:port-number 292 +--rw selector 293 | +--rw facility-list* [facility severity] 294 | | +--rw facility union 295 | | +--rw severity union 296 | | +--rw advanced-compare {select-adv-compare}? 297 | | +--rw compare? enumeration 298 | | +--rw action? enumeration 299 | +--rw pattern-match? string {select-match}? 300 +--rw structured-data? boolean {structured-data}? 301 +--rw facility-override? identityref 302 +--rw source-interface? if:interface-ref {remote-source-interface}? 303 +--rw signing-options! {signed-messages}? 304 +--rw cert-initial-repeat uint16 305 +--rw cert-resend-delay uint16 306 +--rw cert-resend-count uint16 307 +--rw max-delay uint16 308 +--rw number-resends uint16 309 +--rw resend-delay uint16 310 +--rw resend-count uint16 312 Figure 2. ietf-syslog Module Tree 314 4. Syslog YANG Modules 316 4.1. The ietf-syslog-types Module 318 This module references [RFC5424]. 320 file "ietf-syslog-types.yang" 321 module ietf-syslog-types { 322 namespace "urn:ietf:params:xml:ns:yang:ietf-syslog-types"; 323 prefix syslogtypes; 325 organization "IETF NETMOD (NETCONF Data Modeling Language) Working 326 Group"; 327 contact 328 "WG Web: 329 WG List: 331 WG Chair: Lou Berger 332 334 WG Chair: Kent Watsen 335 337 Editor: Kiran Agrahara Sreenivasa 338 340 Editor: Clyde Wildes 341 "; 342 description 343 "This module contains a collection of YANG type definitions for 344 SYSLOG. 346 Copyright (c) 2016 IETF Trust and the persons identified as 347 authors of the code. All rights reserved. 349 Redistribution and use in source and binary forms, with or 350 without modification, is permitted pursuant to, and subject to 351 the license terms contained in, the Simplified BSD License set 352 forth in Section 4.c of the IETF Trust's Legal Provisions 353 Relating to IETF Documents 354 (http://trustee.ietf.org/license-info). 356 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 357 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 358 'OPTIONAL' in the module text are to be interpreted as described 359 in RFC 2119 (http://tools.ietf.org/html/rfc2119). 361 This version of this YANG module is part of RFC XXXX 362 (http://tools.ietf.org/html/rfcXXXX); see the RFC itself for 363 full legal notices."; 365 reference 366 "RFC 5424: The Syslog Protocol"; 368 revision 2017-02-14 { 369 description 370 "Initial Revision"; 371 reference 372 "RFC XXXX: SYSLOG YANG Model"; 374 } 376 typedef severity { 377 type enumeration { 378 enum "emergency" { 379 value 0; 380 description 381 "The severity level 'Emergency' indicating that the system 382 is unusable."; 383 } 384 enum "alert" { 385 value 1; 386 description 387 "The severity level 'Alert' indicating that an action must be 388 taken immediately."; 389 } 390 enum "critical" { 391 value 2; 392 description 393 "The severity level 'Critical' indicating a critical condition."; 394 } 395 enum "error" { 396 value 3; 397 description 398 "The severity level 'Error' indicating an error condition."; 399 } 400 enum "warning" { 401 value 4; 402 description 403 "The severity level 'Warning' indicating a warning condition."; 404 } 405 enum "notice" { 406 value 5; 407 description 408 "The severity level 'Notice' indicating a normal but significant 409 condition."; 410 } 411 enum "info" { 412 value 6; 413 description 414 "The severity level 'Info' indicating an informational message."; 415 } 416 enum "debug" { 417 value 7; 418 description 419 "The severity level 'Debug' indicating a debug-level message."; 420 } 421 } 422 description 423 "The definitions for Syslog message severity as per RFC 5424."; 424 } 426 identity syslog-facility { 427 description 428 "This identity is used as a base for all syslog facilities as 429 per RFC 5424."; 430 } 432 identity kern { 433 base syslog-facility; 434 description 435 "The facility for kernel messages (0) as defined in RFC 5424."; 436 } 438 identity user { 439 base syslog-facility; 440 description 441 "The facility for user-level messages (1) as defined in RFC 5424."; 442 } 444 identity mail { 445 base syslog-facility; 446 description 447 "The facility for the mail system (2) as defined in RFC 5424."; 448 } 450 identity daemon { 451 base syslog-facility; 452 description 453 "The facility for the system daemons (3) as defined in RFC 5424."; 454 } 456 identity auth { 457 base syslog-facility; 458 description 459 "The facility for security/authorization messages (4) as defined 460 in RFC 5424."; 461 } 463 identity syslog { 464 base syslog-facility; 465 description 466 "The facility for messages generated internally by syslogd 467 facility (5) as defined in RFC 5424."; 468 } 470 identity lpr { 471 base syslog-facility; 472 description 473 "The facility for the line printer subsystem (6) as defined in 474 RFC 5424."; 475 } 477 identity news { 478 base syslog-facility; 479 description 480 "The facility for the network news subsystem (7) as defined in 481 RFC 5424."; 483 } 485 identity uucp { 486 base syslog-facility; 487 description 488 "The facility for the UUCP subsystem (8) as defined in RFC 5424."; 489 } 491 identity cron { 492 base syslog-facility; 493 description 494 "The facility for the clock daemon (9) as defined in RFC 5424."; 495 } 497 identity authpriv { 498 base syslog-facility; 499 description 500 "The facility for privileged security/authorization messages (10) 501 as defined in RFC 5424."; 502 } 504 identity ftp { 505 base syslog-facility; 506 description 507 "The facility for the FTP daemon (11) as defined in RFC 5424."; 508 } 510 identity ntp { 511 base syslog-facility; 512 description 513 "The facility for the NTP subsystem (12) as defined in RFC 5424."; 514 } 516 identity audit { 517 base syslog-facility; 518 description 519 "The facility for log audit messages (13) as defined in RFC 5424."; 520 } 522 identity console { 523 base syslog-facility; 524 description 525 "The facility for log alert messages (14) as defined in RFC 5424."; 526 } 528 identity cron2 { 529 base syslog-facility; 530 description 531 "The facility for the second clock daemon (15) as defined in 532 RFC 5424."; 533 } 535 identity local0 { 536 base syslog-facility; 537 description 538 "The facility for local use 0 messages (16) as defined in 539 RFC 5424."; 540 } 542 identity local1 { 543 base syslog-facility; 544 description 545 "The facility for local use 1 messages (17) as defined in 546 RFC 5424."; 547 } 549 identity local2 { 550 base syslog-facility; 551 description 552 "The facility for local use 2 messages (18) as defined in 553 RFC 5424."; 554 } 556 identity local3 { 557 base syslog-facility; 558 description 559 "The facility for local use 3 messages (19) as defined in 560 RFC 5424."; 561 } 563 identity local4 { 564 base syslog-facility; 565 description 566 "The facility for local use 4 messages (20) as defined in 567 RFC 5424."; 568 } 570 identity local5 { 571 base syslog-facility; 572 description 573 "The facility for local use 5 messages (21) as defined in 574 RFC 5424."; 575 } 577 identity local6 { 578 base syslog-facility; 579 description 580 "The facility for local use 6 messages (22) as defined in 581 RFC 5424."; 582 } 584 identity local7 { 585 base syslog-facility; 586 description 587 "The facility for local use 7 messages (23) as defined in 588 RFC 5424."; 589 } 590 } 591 593 Figure 3. ietf-syslog-types Module 595 4.2. The ietf-syslog Module 597 This module imports typedefs from [RFC6021] and [RFC7223], and it 598 references [RFC5424], [RFC5425], [RFC5426], [RFC6587], and [RFC5848]. 600 file "ietf-syslog.yang" 601 module ietf-syslog { 602 namespace "urn:ietf:params:xml:ns:yang:ietf-syslog"; 603 prefix syslog; 605 import ietf-inet-types { 606 prefix inet; 607 } 609 import ietf-interfaces { 610 prefix if; 611 } 613 import ietf-syslog-types { 614 prefix syslogtypes; 615 } 617 organization "IETF NETMOD (NETCONF Data Modeling Language) 618 Working Group"; 619 contact 620 "WG Web: 621 WG List: 623 WG Chair: Lou Berger 624 626 WG Chair: Kent Watsen 627 629 Editor: Kiran Agrahara Sreenivasa 630 632 Editor: Clyde Wildes 633 "; 634 description 635 "This module contains a collection of YANG definitions 636 for syslog configuration. 638 Copyright (c) 2016 IETF Trust and the persons identified as 639 authors of the code. All rights reserved. 641 Redistribution and use in source and binary forms, with or 642 without modification, is permitted pursuant to, and subject to 643 the license terms contained in, the Simplified BSD License set 644 forth in Section 4.c of the IETF Trust's Legal Provisions 645 Relating to IETF Documents 646 (http://trustee.ietf.org/license-info). 648 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 649 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 650 'OPTIONAL' in the module text are to be interpreted as described 651 in RFC 2119 (http://tools.ietf.org/html/rfc2119). 653 This version of this YANG module is part of RFC XXXX 654 (http://tools.ietf.org/html/rfcXXXX); see the RFC itself for 655 full legal notices."; 657 reference 658 "RFC 5424: The Syslog Protocol 659 RFC 5426: Transmission of Syslog Messages over UDP 660 RFC 6587: Transmission of Syslog Messages over TCP 661 RFC 5848: Signed Syslog Messages"; 663 revision 2017-02-14 { 664 description 665 "Initial Revision"; 666 reference 667 "RFC XXXX: Syslog YANG Model"; 668 } 670 feature console-action { 671 description 672 "This feature indicates that the local console action is 673 supported."; 674 } 676 feature file-action { 677 description 678 "This feature indicates that the local file action is 679 supported."; 680 } 682 feature file-limit-size { 683 description 684 "This feature indicates that file logging resources 685 are managed using size and number limits."; 686 } 688 feature file-limit-duration { 689 description 690 "This feature indicates that file logging resources 691 are managed using time based limits."; 692 } 694 feature remote-action { 695 description 696 "This feature indicates that the remote server action is 697 supported."; 698 } 700 feature remote-source-interface { 701 description 702 "This feature indicates that source-interface is supported 703 supported for the remote-action."; 704 } 706 feature select-adv-compare { 707 description 708 "This feature represents the ability to select messages 709 using the additional comparison operators when comparing 710 the syslog message severity."; 711 } 713 feature select-match { 714 description 715 "This feature represents the ability to select messages based 716 on a Posix 1003.2 regular expression pattern match."; 717 } 719 feature structured-data { 720 description 721 "This feature represents the ability to log messages 722 in structured-data format as per RFC 5424."; 723 } 725 feature signed-messages { 726 description 727 "This feature represents the ability to configure signed 728 syslog messages according to RFC 5848."; 729 } 731 grouping severity-filter { 732 description 733 "This grouping defines the processing used to select 734 log messages by comparing syslog message severity using 735 the following processing rules: 736 - if 'none', do not match. 737 - if 'all', match. 738 - else compare message severity with the specified severity 739 according to the default compare rule (all messages of the 740 specified severity and greater match) or if the 741 select-adv-compare feature is present, the advance-compare 742 rule."; 743 leaf severity { 744 type union { 745 type syslogtypes:severity; 746 type enumeration { 747 enum none { 748 value -2; 749 description 750 "This enum describes the case where no severities 751 are selected."; 752 } 753 enum all { 754 value -1; 755 description 756 "This enum describes the case where all severities 757 are selected."; 758 } 759 } 760 } 761 mandatory true; 762 description 763 "This leaf specifies the syslog message severity."; 764 } 765 container advanced-compare { 766 when '../severity != "all" and 767 ../severity != "none"' { 768 description 769 "The advanced compare container is not applicable for severity 770 'all' or severity 'none'"; 771 } 772 if-feature select-adv-compare; 773 leaf compare { 774 type enumeration { 775 enum equals { 776 description 777 "This enum specifies that the severity comparison operation 778 will be equals."; 779 } 780 enum equals-or-higher { 781 description 782 "This enum specifies that the severity comparison operation 783 will be equals or higher."; 784 } 785 } 786 default equals-or-higher; 787 description 788 "The compare can be used to specify the comparison operator that 789 should be used to compare the syslog message severity with the 790 specified severity."; 791 } 792 leaf action { 793 type enumeration { 794 enum log { 795 description 796 "This enum specifies that if the compare operation is true 797 the message will be logged."; 798 } 799 enum block { 800 description 801 "This enum specifies that if the compare operation is true 802 the message will not be logged."; 803 } 804 } 805 default log; 806 description 807 "The action can be used to spectify if the message should be 808 logged or blocked based on the outcome of the compare operation."; 809 } 810 description 811 "This leaf describes additional severity compare operations that can 812 be used in place of the default severity comparison. The compare leaf 813 specifies the type of the compare that is done and the action leaf 814 specifies the intended result. Example: compare->equals and action-> 815 no-match means messages that have a severity that is not equal to the 816 specified severity will be logged."; 817 } 818 } 820 grouping selector { 821 description 822 "This grouping defines a syslog selector which is used to 823 select log messages for the log-action (console, file, 824 remote, etc.). Choose one or both of the following: 825 facility [ ...] 826 pattern-match regular-expression-match-string 827 If both facility and pattern-match are specified, both must 828 match in order for a log message to be selected."; 829 container selector { 830 description 831 "This container describes the log selector parameters 832 for syslog."; 833 list facility-list { 834 key "facility severity"; 835 ordered-by user; 836 description 837 "This list describes a collection of syslog 838 facilities and severities."; 839 leaf facility { 840 type union { 841 type identityref { 842 base syslogtypes:syslog-facility; 843 } 844 type enumeration { 845 enum all { 846 description 847 "This enum describes the case where all 848 facilities are requested."; 849 } 850 } 851 } 852 description 853 "The leaf uniquely identifies a syslog facility."; 854 } 855 uses severity-filter; 856 } 857 leaf pattern-match { 858 if-feature select-match; 859 type string; 860 description 861 "This leaf describes a Posix 1003.2 regular expression 862 string that can be used to select a syslog message for 863 logging. The match is performed on the RFC 5424 864 SYSLOG-MSG field."; 865 } 866 } 867 } 868 grouping structured-data { 869 description 870 "This grouping defines the syslog structured data option 871 which is used to select the format used to write log 872 messages."; 873 leaf structured-data { 874 if-feature structured-data; 875 type boolean; 876 default false; 877 description 878 "This leaf describes how log messages are written. 879 If true, messages will be written with one or more 880 STRUCTURED-DATA elements as per RFC5424; if false, 881 messages will be written with STRUCTURED-DATA = 882 NILVALUE."; 883 } 884 } 886 container syslog { 887 presence "Enables logging."; 888 description 889 "This container describes the configuration parameters for 890 syslog."; 891 container actions { 892 description 893 "This container describes the log-action parameters 894 for syslog."; 895 container console { 896 if-feature console-action; 897 presence "Enables logging to the console"; 898 description 899 "This container describes the configuration parameters for 900 console logging."; 901 uses selector; 902 } 903 container file { 904 if-feature file-action; 905 description 906 "This container describes the configuration parameters for 907 file logging. If file-archive limits are not supplied, it 908 is assumed that the local implementation defined limits will 909 be used."; 910 list log-file { 911 key "name"; 912 description 913 "This list describes a collection of local logging 914 files."; 915 leaf name { 916 type inet:uri { 917 pattern 'file:.*'; 918 } 919 description 920 "This leaf specifies the name of the log file which 921 MUST use the uri scheme file:."; 923 } 924 uses selector; 925 uses structured-data; 926 container file-rotation { 927 description 928 "This container describes the configuration 929 parameters for log file rotation."; 930 leaf number-of-files { 931 if-feature file-limit-size; 932 type uint32; 933 default 1; 934 description 935 "This leaf specifies the maximum number of log 936 files retained. Specify 1 for implementations 937 that only support one log file."; 938 } 939 leaf max-file-size { 940 if-feature file-limit-size; 941 type uint32; 942 units "megabytes"; 943 description 944 "This leaf specifies the maximum log file size."; 945 } 946 leaf rollover { 947 if-feature file-limit-duration; 948 type uint32; 949 units "minutes"; 950 description 951 "This leaf specifies the length of time that log 952 events should be written to a specific log file. 953 Log events that arrive after the rollover period 954 cause the current log file to be closed and a new 955 log file to be opened."; 956 } 957 leaf retention { 958 if-feature file-limit-duration; 959 type uint32; 960 units "hours"; 961 description 962 "This leaf specifies the length of time that 963 completed/closed log event files should be stored 964 in the file system before they are deleted."; 965 } 966 } 967 } 968 } 969 container remote { 970 if-feature remote-action; 971 description 972 "This container describes the configuration parameters for 973 forwarding syslog messages to remote relays or collectors."; 974 list destination { 975 key "name"; 976 description 977 "This list describes a collection of remote logging 978 destinations."; 979 leaf name { 980 type string; 981 description 982 "An arbitrary name for the endpoint to connect to."; 983 } 984 choice transport { 985 mandatory true; 986 description 987 "This choice describes the transport option."; 988 case tcp { 989 container tcp { 990 description 991 "This container describes the TCP transport 992 options."; 993 reference 994 "RFC 6587: Transmission of Syslog Messages over TCP"; 995 leaf address { 996 type inet:host; 997 description 998 "The leaf uniquely specifies the address of 999 the remote host. One of the following must 1000 be specified: an ipv4 address, an ipv6 1001 address, or a host name."; 1002 } 1003 leaf port { 1004 type inet:port-number; 1005 default 514; 1006 description 1007 "This leaf specifies the port number used to 1008 deliver messages to the remote server."; 1009 } 1010 } 1011 } 1012 case udp { 1013 container udp { 1014 description 1015 "This container describes the UDP transport 1016 options."; 1017 reference 1018 "RFC 5426: Transmission of Syslog Messages over 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 } 1037 uses selector; 1038 uses structured-data; 1039 leaf facility-override { 1040 type identityref { 1041 base syslogtypes:syslog-facility; 1042 } 1043 description 1044 "If specified, this leaf specifies the facility used 1045 to override the facility in messages delivered to the 1046 remote server."; 1047 } 1048 leaf source-interface { 1049 if-feature remote-source-interface; 1050 type if:interface-ref; 1051 description 1052 "This leaf sets the source interface to be used to send 1053 message to the remote syslog server. If not set, 1054 messages sent to a remote syslog server will 1055 contain the IP address of the interface the syslog 1056 message uses to exit the network element"; 1057 } 1058 container signing-options { 1059 if-feature signed-messages; 1060 presence 1061 "If present, syslog-signing options is activated."; 1062 description 1063 "This container describes the configuration 1064 parameters for signed syslog messages as described 1065 by RFC 5848."; 1066 reference 1067 "RFC 5848: Signed Syslog Messages"; 1068 leaf cert-initial-repeat { 1069 type uint16; 1070 mandatory true; 1071 description 1072 "This leaf specifies the number of times each 1073 Certificate Block should be sent before the first 1074 message is sent."; 1075 } 1076 leaf cert-resend-delay { 1077 type uint16; 1078 units "seconds"; 1079 mandatory true; 1080 description 1081 "This leaf specifies the maximum time delay in 1082 seconds until resending the Certificate Block."; 1083 } 1084 leaf cert-resend-count { 1085 type uint16; 1086 mandatory true; 1087 description 1088 "This leaf specifies the maximum number of other 1089 syslog messages to send until resending the 1090 Certificate Block."; 1091 } 1092 leaf max-delay { 1093 type uint16; 1094 units "seconds"; 1095 mandatory true; 1096 description 1097 "This leaf specifies when to generate a new 1098 Signature Block. If this many seconds have 1099 elapsed since the message with the first message 1100 number of the Signature Block was sent, a new 1101 Signature Block should be generated."; 1102 } 1103 leaf number-resends { 1104 type uint16; 1105 mandatory true; 1106 description 1107 "This leaf specifies the number of times a 1108 Signature Block is resent. (It is recommended to 1109 select a value of greater than 0 in particular 1110 when the UDP transport [RFC5426] is used.)."; 1111 } 1112 leaf resend-delay { 1113 type uint16; 1114 units "seconds"; 1115 mandatory true; 1116 description 1117 "This leaf specifies when to send the next 1118 Signature Block transmission based on time. If 1119 this many seconds have elapsed since the previous 1120 sending of this Signature Block, resend it."; 1121 } 1122 leaf resend-count { 1123 type uint16; 1124 mandatory true; 1125 description 1126 "This leaf specifies when to send the next 1127 Signature Block transmission based on a count. 1128 If this many other syslog messages have been sent 1129 since the previous sending of this Signature 1130 Block, resend it."; 1131 } 1132 } 1133 } 1134 } 1135 } 1136 } 1137 } 1138 1139 Figure 4. ietf-syslog Module 1141 5. Usage Examples 1143 Requirement: 1144 Enable console logging of syslogs of severity critical 1146 Here is the example syslog configuration xml: 1147 1148 1150 1151 1152 1153 1154 all 1155 critical 1156 1157 1158 1159 1160 1161 1163 Enable remote logging of syslogs to udp destination 2001:db8:a0b:12f0::1 1164 for facility auth, severity error 1166 1167 1169 1170 1171 1172 remote1 1173 1174
2001:db8:a0b:12f0::1
1175 1176 1177 1178 1180 syslogtypes:auth 1181 error 1182 1183 1184 1185 1186 1187 1188 1190 Figure 5. ietf-syslog Examples 1192 6. Acknowledgements 1194 The authors wish to thank the following who commented on this 1195 proposal: 1197 Andy Bierman 1198 Martin Bjorklund 1199 Alex Campbell 1200 Jim Gibson 1201 Jeffrey Haas 1202 John Heasley 1203 Giles Heron 1204 Lisa Huang 1205 Mahesh Jethanandani 1206 Jeffrey K Lange 1207 Jan Lindblad 1208 Chris Lonvick 1209 Tom Petch 1210 Juergen Schoenwaelder 1211 Phil Shafer 1212 Jason Sterne 1213 Peter Van Horne 1214 Bert Wijnen 1215 Aleksandr Zhdankin 1217 7. IANA Considerations 1219 This document registers two URIs in the IETF XML registry [RFC3688]. 1221 Following the format in RFC 3688, the following registration is 1222 requested to be made: 1224 URI: urn:ietf:params:xml:ns:yang:ietf-syslog-types 1226 Registrant Contact: The IESG. 1228 XML: N/A, the requested URI is an XML namespace. 1230 This document registers a YANG module in the YANG Module Names 1231 registry [RFC6020]. 1233 name: ietf-syslog-types namespace: urn:ietf:params:xml:ns:yang:ietf- 1234 syslog-types 1236 prefix: ietf-syslog-types reference: RFC XXXX 1238 Following the format in RFC 3688, the following registration is 1239 requested to be made: 1241 URI: urn:ietf:params:xml:ns:yang:ietf-syslog 1243 Registrant Contact: The IESG. 1245 XML: N/A, the requested URI is an XML namespace. 1247 This document registers a YANG module in the YANG Module Names 1248 registry [RFC6020]. 1250 name: ietf-syslog namespace: urn:ietf:params:xml:ns:yang:ietf-syslog 1252 prefix: ietf-syslog 1254 reference: RFC XXXX 1256 8. Security Considerations 1258 The YANG module defined in this memo is designed to be accessed via 1259 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1260 secure transport layer and the mandatory-to-implement secure 1261 transport is SSH [RFC6242]. The NETCONF access control model 1262 [RFC6536] provides the means to restrict access for particular 1263 NETCONF users to a pre-configured subset of all available NETCONF 1264 protocol operations and content. 1266 There are a number of data nodes defined in the YANG module which are 1267 writable/creatable/deletable (i.e., config true, which is the 1268 default). These data nodes may be considered sensitive or vulnerable 1269 in some network environments. Write operations (e.g., ) 1270 to these data nodes without proper protection can have a negative 1271 effect on network operations. 1273 8.1. Resource Constraints 1275 Network administrators must take the time to estimate the appropriate 1276 memory limits caused by the configuration of actions/buffer using 1277 buffer-limit-bytes and/or buffer-limit-messages where necessary to 1278 limit the amount of memory used. 1280 Network administrators must take the time to estimate the appropriate 1281 storage capacity caused by the configuration of actions/file using 1282 file-archive attributes to limit storage used. 1284 It is the responsibility of the network administrator to ensure that 1285 the configured message flow does not overwhelm system resources. 1287 8.2. Inappropriate Configuration 1289 It is the responsibility of the network administrator to ensure that 1290 the messages are actually going to the intended recipients. 1292 9. References 1294 9.1. Normative References 1296 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1297 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1298 RFC2119, March 1997, . 1301 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, DOI 1302 10.17487/RFC5424, March 2009, . 1305 [RFC5426] Okmianski, A., "Transmission of Syslog Messages over UDP", 1306 RFC 5426, DOI 10.17487/RFC5426, March 2009, . 1309 [RFC5848] Kelsey, J., Callas, J. and A. Clemm, "Signed Syslog 1310 Messages", RFC 5848, DOI 10.17487/RFC5848, May 2010, 1311 . 1313 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1314 the Network Configuration Protocol (NETCONF)", RFC 6020, 1315 DOI 10.17487/RFC6020, October 2010, . 1318 [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 1319 6021, DOI 10.17487/RFC6021, October 2010, . 1322 [RFC6587] Gerhards, R. and C. Lonvick, "Transmission of Syslog 1323 Messages over TCP", RFC 6587, DOI 10.17487/RFC6587, April 1324 2012, . 1326 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1327 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1328 . 1330 9.2. Informative References 1332 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1333 DOI 10.17487/RFC3688, January 2004, . 1336 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J.Ed., 1337 and A. Bierman, Ed., "Network Configuration Protocol 1338 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1339 . 1341 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1342 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1343 . 1345 Appendix A. Implementor Guidelines 1347 Appendix A.1. Extending Facilities 1348 Many vendors extend the list of facilities available for logging in 1349 their implementation. Additional facilities may not work with the 1350 syslog protocol as defined in [RFC5424] and hence such facilities 1351 apply for local syslog-like logging functionality. 1353 The following is an example that shows how additional facilities 1354 could be added to the list of available facilities (in this example 1355 two facilities are added): 1357 module vendor-syslog-types-example { 1358 namespace "urn:vendor:params:xml:ns:yang:vendor-syslog-types"; 1359 prefix vendor-syslogtypes; 1361 import ietf-syslog-types { 1362 prefix syslogtypes; 1363 } 1365 organization "Example, Inc."; 1366 contact 1367 "Example, Inc. 1368 Customer Service 1370 E-mail: syslog-yang@example.com"; 1372 description 1373 "This module contains a collection of vendor-specific YANG type 1374 definitions for SYSLOG."; 1376 revision 2016-11-13 { 1377 description 1378 "Version 1.0"; 1379 reference 1380 "Vendor SYSLOG Types: SYSLOG YANG Model"; 1381 } 1383 identity vendor_specific_type_1 { 1384 base syslogtypes:syslog-facility; 1385 } 1387 identity vendor_specific_type_2 { 1388 base syslogtypes:syslog-facility; 1389 } 1390 } 1392 Authors' Addresses 1393 Clyde Wildes, editor 1394 Cisco Systems Inc. 1395 170 West Tasman Drive 1396 San Jose, CA 95134 1397 US 1399 Phone: +1 408 527-2672 1400 Email: cwildes@cisco.com 1402 Kiran Koushik, editor 1403 Cisco Systems Inc. 1404 12515Research Blvd., Building 4 1405 Austin, TX 78759 1406 US 1408 Phone: +1 512 378-1482 1409 Email: kkoushik@cisco.com