idnits 2.17.1 draft-ietf-netmod-syslog-model-18.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 is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 347 has weird spacing: '...gorithm ide...' -- The document date (December 12, 2017) is 2325 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: 'RFC6021' is mentioned on line 374, but not defined ** Obsolete undefined reference: RFC 6021 (Obsoleted by RFC 6991) == Unused Reference: 'RFC6691' is defined on line 1446, but no explicit reference was found in the text == Unused Reference: 'RFC7895' is defined on line 1454, but no explicit reference was found in the text ** Downref: Normative reference to an Historic RFC: RFC 6587 ** Obsolete normative reference: RFC 6691 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 6 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). 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: June 13, 2018 Verizon Wireless 6 December 12, 2017 8 A YANG Data Model for Syslog Configuration 9 draft-ietf-netmod-syslog-model-18 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." 48 This Internet-Draft will expire on June 13, 2018. 50 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 Diagram Notation . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . 9 74 4.1. The ietf-syslog Module . . . . . . . . . . . . . . . . . . 9 75 5. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . 26 76 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 78 7.1. The YANG Module Names Registry . . . . . . . . . . . . . . 28 79 8. Security Considerations . . . . . . . . . . . . . . . . . . . 29 80 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 81 9.1. Normative References . . . . . . . . . . . . . . . . . . . 29 82 9.2. Informative References . . . . . . . . . . . . . . . . . . 31 83 Appendix A. Implementor Guidelines . . . . . . . . . . . . . . . . 31 84 Appendix A.1. Extending Facilities . . . . . . . . . . . . . . 31 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 87 1. Introduction 89 Operating systems, processes and applications generate messages 90 indicating their own status or the occurrence of events. These 91 messages are useful for managing and/or debugging the network and its 92 services. The BSD syslog protocol is a widely adopted protocol that 93 is used for transmission and processing of the message. 95 Since each process, application and operating system was written 96 somewhat independently, there is little uniformity to the content of 97 syslog messages. For this reason, no assumption is made upon the 98 formatting or contents of the messages. The protocol is simply 99 designed to transport these event messages. No acknowledgement of 100 the receipt is made. 102 Essentially, a syslog process receives messages (from the kernel, 103 processes, applications or other syslog processes) and processes 104 them. The processing may involve logging to a local file, and/or 105 displaying on console, and/or relaying to syslog processes on other 106 machines. The processing is determined by the "facility" that 107 originated the message and the "severity" assigned to the message by 108 the facility. 110 We are using definitions of syslog protocol from [RFC5424] in this 111 RFC. 113 1.1. Requirements Language 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in [RFC2119] and 118 [RFC8174]. 120 1.2. Terminology 122 The term "originator" is defined in [RFC5424]: an "originator" 123 generates syslog content to be carried in a message. 125 The term "relay" is defined in [RFC5424]: a "relay" forwards 126 messages, accepting messages from originators or other relays and 127 sending them to collectors or other relays 129 The term "collectors" is defined in [RFC5424]: a "collector" gathers 130 syslog content for further analysis. 132 The term "action" refers to the processing that takes place for each 133 syslog message received. 135 1.3. Tree Diagram Notation 137 A simplified graphical representation of the data models is used in 138 this document. The meaning of the symbols in these diagrams is as 139 follows: 141 o Brackets "[" and "]" enclose list keys. 143 o Braces "{" and "}" enclose feature names, and indicate that the 144 named feature must be present for the subtree to be present. 146 o Abbreviations before data node names: "rw" means configuration 147 (read-write) and "ro" state data (read-only). 149 o Symbols after data node names: "?" means an optional node, "!" 150 means a presence container, and "*" denotes a list and leaf-list. 152 o Parentheses enclose choice and case nodes, and case nodes are also 153 marked with a colon (":"). 155 o Ellipsis ("...") stands for contents of subtrees that are not 156 shown. 158 2. Problem Statement 160 This document defines a YANG [RFC7950] configuration data model that 161 may be used to configure the syslog feature running on a system. 162 YANG models can be used with network management protocols such as 163 NETCONF [RFC6241] to install, manipulate, and delete the 164 configuration of network devices. 166 The data model makes use of the YANG "feature" construct which allows 167 implementations to support only those syslog features that lie within 168 their capabilities. 170 This module can be used to configure the syslog application 171 conceptual layers as implemented on the target system. 173 3. Design of the Syslog Model 175 The syslog model was designed by comparing various syslog features 176 implemented by various vendors' in different implementations. 178 This draft addresses the common leafs between implementations and 179 creates a common model, which can be augmented with proprietary 180 features, if necessary. This model is designed to be very simple for 181 maximum flexibility. 183 Some optional features are defined in this document to specify 184 functionality that is present in specific vendor configurations. 186 Syslog consists of originators and collectors. The following diagram 187 shows syslog messages flowing from an originator, to collectors where 188 filtering can take place. 190 Originators 191 +-------------+ +-------------+ +-------------+ +-------------+ 192 | Various | | OS | | | | Remote | 193 | Components | | Kernel | | Line Cards | | Servers | 194 +-------------+ +-------------+ +-------------+ +-------------+ 196 +-------------+ +-------------+ +-------------+ +-------------+ 197 | SNMP | | Interface | | Standby | | Syslog | 198 | Events | | Events | | Supervisor | | Itself | 199 +-------------+ +-------------+ +-------------+ +-------------+ 201 | | 202 +----------------------------------------------------------------+ 203 | 204 | 205 | 206 | 207 +-------------+--------------+ 208 | | | 209 v v v 210 Collectors 211 +----------+ +----------+ +----------------+ 212 | | | Log | |Remote Relay(s)/| 213 | Console | | File(s) | |Collector(s) | 214 +----------+ +----------+ +----------------+ 216 Figure 1. Syslog Processing Flow 218 Collectors are configured using the leaves in the syslog model 219 "actions" container which correspond to each message collector: 221 console 223 log file(s) 225 remote relay(s)/collector(s) 227 Within each action, a selector is used to filter syslog messages. A 228 selector consists of a list of one or more facility-severity matches, 229 and, if supported via the select-match feature, an optional regular 230 expression pattern match that is performed on the [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 236 and the message severity matches S 237 and/or the message text matches the regex pattern (if it 238 is present) 240 The facility is one of a specific syslog-facility, or all facilities. 242 The severity is one of type syslog-severity, all severities, or none. 243 None is a special case that can be used to disable a filter. When 244 filtering severity, the default comparison is that messages of the 245 specified severity and higher are selected to be logged. This is 246 shown in the model as "default equals-or-higher". This behavior can 247 be altered if the select-adv-compare feature is enabled to specify a 248 compare operation and an action. Compare operations are: "equals" to 249 select messages with this single severity, or "equals-or-higher" to 250 select messages of the specified severity and higher. Actions are 251 used to log the message or block the message from being logged. 253 Many vendors extend the list of facilities available for logging in 254 their implementation. An example is included in Extending Facilities 255 (Appendix A.1). 257 3.1. Syslog Module 259 A simplified graphical representation of the data model is used in 260 this document. Please see Section 1.3 for tree diagram notation. 262 module: ietf-syslog 263 +--rw syslog! 264 +--rw actions 265 +--rw console! {console-action}? 266 | +--rw facility-filter 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 file {file-action}? 275 | +--rw log-file* [name] 276 | +--rw name inet:uri 277 | +--rw facility-filter 278 | | +--rw facility-list* [facility severity] 279 | | +--rw facility union 280 | | +--rw severity union 281 | | +--rw advanced-compare {select-adv-compare}? 282 | | +--rw compare? enumeration 283 | | +--rw action? enumeration 284 | +--rw pattern-match? string {select-match}? 285 | +--rw structured-data? boolean {structured-data}? 286 | +--rw file-rotation 287 | +--rw number-of-files? uint32 {file-limit-size}? 288 | +--rw max-file-size? uint32 {file-limit-size}? 289 | +--rw rollover? uint32 290 | | {file-limit-duration}? 291 | +--rw retention? uint32 292 | {file-limit-duration}? 293 +--rw remote {remote-action}? 294 +--rw destination* [name] 295 +--rw name string 296 +--rw (transport) 297 | +--:(tcp) 298 | | +--rw tcp 299 | | +--rw address? inet:host 300 | | +--rw port? inet:port-number 301 | +--:(udp) 302 | | +--rw udp 303 | | +--rw address? inet:host 304 | | +--rw port? inet:port-number 305 | +--:(tls) 306 | +--rw tls 307 | +--rw address? inet:host 308 | +--rw port? inet:port-number 309 | +--rw client-auth 310 | | +--rw (auth-type)? 311 | | +--:(certificate) 312 | | +--rw certificate? leafref 313 | +--rw server-auth 314 | | +--rw pinned-ca-certs? leafref 315 | | +--rw pinned-server-certs? leafref 316 | +--rw hello-params 317 | {tls-client-hello-params-config}? 318 | +--rw tls-versions 319 | | +--rw tls-version* identityref 320 | +--rw cipher-suites 321 | +--rw cipher-suite* identityref 322 +--rw facility-filter 323 | +--rw facility-list* [facility severity] 324 | +--rw facility union 325 | +--rw severity union 326 | +--rw advanced-compare {select-adv-compare}? 327 | +--rw compare? enumeration 328 | +--rw action? enumeration 329 +--rw pattern-match? string {select-match}? 330 +--rw structured-data? boolean {structured-data}? 331 +--rw facility-override? identityref 332 +--rw source-interface? if:interface-ref 333 | {remote-source-interface}? 334 +--rw signing-options! {signed-messages}? 335 +--rw cert-signers 336 +--rw cert-signer* [name] 337 | +--rw name string 338 | +--rw certificate 339 | | +--rw algorithm? 340 | | | identityref 341 | | +--rw private-key? 342 | | | union 343 | | +--rw public-key? 344 | | | binary 345 | | +---x generate-private-key 346 | | | +---w input 347 | | | +---w algorithm identityref 348 | | +--rw certificates 349 | | | +--rw certificate* [name] 350 | | | +--rw name string 351 | | | +--rw value? binary 352 | | +---x generate-certificate-signing-request 353 | | +---w input 354 | | | +---w subject binary 355 | | | +---w attributes? binary 356 | | +--ro output 357 | | +--ro certificate-signing-request 358 | | binary 359 | +--rw hash-algorithm? enumeration 360 +--rw cert-initial-repeat? uint32 361 +--rw cert-resend-delay? uint32 362 +--rw cert-resend-count? uint32 363 +--rw sig-max-delay? uint32 364 +--rw sig-number-resends? uint32 365 +--rw sig-resend-delay? uint32 366 +--rw sig-resend-count? uint32 368 Figure 2. ietf-syslog Module Tree 370 4. Syslog YANG Module 372 4.1. The ietf-syslog Module 374 This module imports typedefs from [RFC6021], [RFC7223], groupings 375 from [RFC yyyy], and [RFC xxxx], and it references [RFC5424], 376 [RFC5425], [RFC5426], [RFC6587], and [RFC5848]. 378 file "ietf-syslog.yang@2017-12-12.yang" 379 module ietf-syslog { 380 yang-version 1.1; 382 namespace "urn:ietf:params:xml:ns:yang:ietf-syslog"; 383 prefix syslog; 385 import ietf-inet-types { 386 prefix inet; 387 reference 388 "RFC 6991: INET Types Model"; 389 } 391 import ietf-interfaces { 392 prefix if; 393 reference 394 "RFC 7223: Interfaces Model"; 395 } 397 import ietf-tls-client { 398 prefix tlsc; 399 reference 400 "RFC xxxx: Keystore Model"; 401 } 403 import ietf-keystore { 404 prefix ks; 405 reference 406 "RFC yyyy: TLS Client and Server Models"; 407 } 409 organization "IETF 410 NETMOD (Network Modeling) Working Group"; 412 contact 413 "WG Web: 414 WG List: 416 Editor: Kiran Agrahara Sreenivasa 417 420 Editor: Clyde Wildes 421 "; 422 description 423 "This module contains a collection of YANG definitions 424 for syslog configuration. 426 Copyright (c) 2017 IETF Trust and the persons identified as 427 authors of the code. All rights reserved. 429 Redistribution and use in source and binary forms, with or 430 without modification, is permitted pursuant to, and subject to 431 the license terms contained in, the Simplified BSD License set 432 forth in Section 4.c of the IETF Trust's Legal Provisions 433 Relating to IETF Documents 434 (http://trustee.ietf.org/license-info). 436 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 437 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 438 'OPTIONAL' in the module text are to be interpreted as 439 described in RFC 2119 (http://tools.ietf.org/html/rfc2119). 441 This version of this YANG module is part of RFC zzzz 442 (http://tools.ietf.org/html/rfczzzz); see the RFC itself for 443 full legal notices."; 445 revision 2017-12-12 { 446 description 447 "Initial Revision"; 448 reference 449 "RFC zzzz: Syslog YANG Model"; 450 } 452 feature console-action { 453 description 454 "This feature indicates that the local console action is 455 supported."; 456 } 458 feature file-action { 459 description 460 "This feature indicates that the local file action is 461 supported."; 462 } 464 feature file-limit-size { 465 description 466 "This feature indicates that file logging resources 467 are managed using size and number limits."; 468 } 470 feature file-limit-duration { 471 description 472 "This feature indicates that file logging resources 473 are managed using time based limits."; 474 } 476 feature remote-action { 477 description 478 "This feature indicates that the remote server action is 479 supported."; 480 } 482 feature remote-source-interface { 483 description 484 "This feature indicates that source-interface is supported 485 supported for the remote-action."; 486 } 488 feature select-adv-compare { 489 description 490 "This feature represents the ability to select messages 491 using the additional comparison operators when comparing 492 the syslog message severity."; 493 } 495 feature select-match { 496 description 497 "This feature represents the ability to select messages 498 based on a Posix 1003.2 regular expression pattern match."; 499 } 501 feature structured-data { 502 description 503 "This feature represents the ability to log messages 504 in structured-data format."; 505 reference 506 "RFC 5424: The Syslog Protocol"; 507 } 509 feature signed-messages { 510 description 511 "This feature represents the ability to configure signed 512 syslog messages."; 513 reference 514 "RFC 5848: Signed Syslog Messages"; 515 } 517 typedef syslog-severity { 518 type enumeration { 519 enum "emergency" { 520 value 0; 521 description 522 "The severity level 'Emergency' indicating that the 523 system is unusable."; 524 } 525 enum "alert" { 526 value 1; 527 description 528 "The severity level 'Alert' indicating that an action 529 must be taken immediately."; 530 } 531 enum "critical" { 532 value 2; 533 description 534 "The severity level 'Critical' indicating a critical 535 condition."; 536 } 537 enum "error" { 538 value 3; 539 description 540 "The severity level 'Error' indicating an error 541 condition."; 542 } 543 enum "warning" { 544 value 4; 545 description 546 "The severity level 'Warning' indicating a warning 547 condition."; 548 } 549 enum "notice" { 550 value 5; 551 description 552 "The severity level 'Notice' indicating a normal but 553 significant condition."; 554 } 555 enum "info" { 556 value 6; 557 description 558 "The severity level 'Info' indicating an informational 559 message."; 560 } 561 enum "debug" { 562 value 7; 563 description 564 "The severity level 'Debug' indicating a debug-level 565 message."; 566 } 567 } 568 description 569 "The definitions for Syslog message severity."; 570 reference 571 "RFC 5424: The Syslog Protocol"; 572 } 574 identity syslog-facility { 575 description 576 "This identity is used as a base for all syslog facilities."; 577 reference 578 "RFC 5424: The Syslog Protocol"; 579 } 581 identity kern { 582 base syslog-facility; 583 description 584 "The facility for kernel messages (0)."; 585 reference 586 "RFC 5424: The Syslog Protocol"; 587 } 589 identity user { 590 base syslog-facility; 591 description 592 "The facility for user-level messages (1)."; 594 reference 595 "RFC 5424: The Syslog Protocol"; 596 } 598 identity mail { 599 base syslog-facility; 600 description 601 "The facility for the mail system (2)."; 602 reference 603 "RFC 5424: The Syslog Protocol"; 604 } 606 identity daemon { 607 base syslog-facility; 608 description 609 "The facility for the system daemons (3)."; 610 reference 611 "RFC 5424: The Syslog Protocol"; 612 } 614 identity auth { 615 base syslog-facility; 616 description 617 "The facility for security/authorization messages (4)."; 618 reference 619 "RFC 5424: The Syslog Protocol"; 620 } 622 identity syslog { 623 base syslog-facility; 624 description 625 "The facility for messages generated internally by syslogd 626 facility (5)."; 627 reference 628 "RFC 5424: The Syslog Protocol"; 629 } 631 identity lpr { 632 base syslog-facility; 633 description 634 "The facility for the line printer subsystem (6)."; 635 reference 636 "RFC 5424: The Syslog Protocol"; 637 } 639 identity news { 640 base syslog-facility; 641 description 642 "The facility for the network news subsystem (7)."; 643 reference 644 "RFC 5424: The Syslog Protocol"; 645 } 647 identity uucp { 648 base syslog-facility; 649 description 650 "The facility for the UUCP subsystem (8)."; 651 reference 652 "RFC 5424: The Syslog Protocol"; 653 } 655 identity cron { 656 base syslog-facility; 657 description 658 "The facility for the clock daemon (9)."; 659 reference 660 "RFC 5424: The Syslog Protocol"; 661 } 663 identity authpriv { 664 base syslog-facility; 665 description 666 "The facility for privileged security/authorization messages 667 (10)."; 668 reference 669 "RFC 5424: The Syslog Protocol"; 670 } 672 identity ftp { 673 base syslog-facility; 674 description 675 "The facility for the FTP daemon (11)."; 676 reference 677 "RFC 5424: The Syslog Protocol"; 678 } 680 identity ntp { 681 base syslog-facility; 682 description 683 "The facility for the NTP subsystem (12)."; 684 reference 685 "RFC 5424: The Syslog Protocol"; 686 } 688 identity audit { 689 base syslog-facility; 690 description 691 "The facility for log audit messages (13)."; 692 reference 693 "RFC 5424: The Syslog Protocol"; 694 } 696 identity console { 697 base syslog-facility; 698 description 699 "The facility for log alert messages (14)."; 700 reference 701 "RFC 5424: The Syslog Protocol"; 703 } 705 identity cron2 { 706 base syslog-facility; 707 description 708 "The facility for the second clock daemon (15)."; 709 reference 710 "RFC 5424: The Syslog Protocol"; 711 } 713 identity local0 { 714 base syslog-facility; 715 description 716 "The facility for local use 0 messages (16)."; 717 reference 718 "RFC 5424: The Syslog Protocol"; 719 } 721 identity local1 { 722 base syslog-facility; 723 description 724 "The facility for local use 1 messages (17)."; 725 reference 726 "RFC 5424: The Syslog Protocol"; 727 } 729 identity local2 { 730 base syslog-facility; 731 description 732 "The facility for local use 2 messages (18)."; 733 reference 734 "RFC 5424: The Syslog Protocol"; 735 } 737 identity local3 { 738 base syslog-facility; 739 description 740 "The facility for local use 3 messages (19)."; 741 reference 742 "RFC 5424: The Syslog Protocol"; 743 } 745 identity local4 { 746 base syslog-facility; 747 description 748 "The facility for local use 4 messages (20)."; 749 reference 750 "RFC 5424: The Syslog Protocol"; 751 } 753 identity local5 { 754 base syslog-facility; 755 description 756 "The facility for local use 5 messages (21)."; 758 reference 759 "RFC 5424: The Syslog Protocol"; 760 } 762 identity local6 { 763 base syslog-facility; 764 description 765 "The facility for local use 6 messages (22)."; 766 reference 767 "RFC 5424: The Syslog Protocol"; 768 } 770 identity local7 { 771 base syslog-facility; 772 description 773 "The facility for local use 7 messages (23)."; 774 reference 775 "RFC 5424: The Syslog Protocol"; 776 } 778 grouping severity-filter { 779 description 780 "This grouping defines the processing used to select 781 log messages by comparing syslog message severity using 782 the following processing rules: 783 - if 'none', do not match. 784 - if 'all', match. 785 - else compare message severity with the specified severity 786 according to the default compare rule (all messages of the 787 specified severity and greater match) or if the 788 select-adv-compare feature is present, the advance-compare 789 rule."; 790 leaf severity { 791 type union { 792 type syslog-severity; 793 type enumeration { 794 enum none { 795 value 2147483647; 796 description 797 "This enum describes the case where no severities 798 are selected."; 799 } 800 enum all { 801 value -2147483648; 802 description 803 "This enum describes the case where all severities 804 are selected."; 805 } 806 } 807 } 808 mandatory true; 809 description 810 "This leaf specifies the syslog message severity."; 811 } 812 container advanced-compare { 813 when '../severity != "all" and 814 ../severity != "none"' { 815 description 816 "The advanced compare container is not applicable for 817 severity 'all' or severity 'none'"; 818 } 819 if-feature select-adv-compare; 820 leaf compare { 821 type enumeration { 822 enum equals { 823 description 824 "This enum specifies that the severity comparison 825 operation will be equals."; 826 } 827 enum equals-or-higher { 828 description 829 "This enum specifies that the severity comparison 830 operation will be equals or higher."; 831 } 832 } 833 default equals-or-higher; 834 description 835 "The compare can be used to specify the comparison 836 operator that should be used to compare the syslog message 837 severity with the specified severity."; 838 } 839 leaf action { 840 type enumeration { 841 enum log { 842 description 843 "This enum specifies that if the compare operation is 844 true the message will be logged."; 845 } 846 enum block { 847 description 848 "This enum specifies that if the compare operation is 849 true the message will not be logged."; 850 } 851 } 852 default log; 853 description 854 "The action can be used to spectify if the message should 855 be logged or blocked based on the outcome of the compare 856 operation."; 857 } 858 description 859 "This container describes additional severity compare 860 operations that can be used in place of the default 861 severity comparison. The compare leaf specifies the type of 862 the compare that is done and the action leaf specifies the 863 intended result. 864 Example: compare->equals and action->no-match means 865 messages that have a severity that is not equal to the 866 specified severity will be logged."; 867 } 868 } 870 grouping selector { 871 description 872 "This grouping defines a syslog selector which is used to 873 select log messages for the log-actions (console, file, 874 remote, etc.). Choose one or both of the following: 875 facility [ ...] 876 pattern-match regular-expression-match-string 877 If both facility and pattern-match are specified, both must 878 match in order for a log message to be selected."; 879 container facility-filter { 880 description 881 "This container describes the syslog filter parameters."; 882 list facility-list { 883 key "facility severity"; 884 ordered-by user; 885 description 886 "This list describes a collection of syslog 887 facilities and severities."; 888 leaf facility { 889 type union { 890 type identityref { 891 base syslog-facility; 892 } 893 type enumeration { 894 enum all { 895 description 896 "This enum describes the case where all 897 facilities are requested."; 898 } 899 } 900 } 901 description 902 "The leaf uniquely identifies a syslog facility."; 903 } 904 uses severity-filter; 905 } 906 } 907 leaf pattern-match { 908 if-feature select-match; 909 type string; 910 description 911 "This leaf describes a Posix 1003.2 regular expression 912 string that can be used to select a syslog message for 913 logging. The match is performed on the SYSLOG-MSG field."; 914 reference 915 "RFC 5424: The Syslog Protocol 916 Std-1003.1-2008 Regular Expressions"; 917 } 918 } 919 grouping structured-data { 920 description 921 "This grouping defines the syslog structured data option 922 which is used to select the format used to write log 923 messages."; 924 leaf structured-data { 925 if-feature structured-data; 926 type boolean; 927 default false; 928 description 929 "This leaf describes how log messages are written. 930 If true, messages will be written with one or more 931 STRUCTURED-DATA elements; if false, messages will be 932 written with STRUCTURED-DATA = NILVALUE."; 933 reference 934 "RFC 5424: The Syslog Protocol"; 935 } 936 } 938 container syslog { 939 presence "Enables logging."; 940 description 941 "This container describes the configuration parameters for 942 syslog."; 943 container actions { 944 description 945 "This container describes the log-action parameters 946 for syslog."; 947 container console { 948 if-feature console-action; 949 presence "Enables logging to the console"; 950 description 951 "This container describes the configuration parameters 952 for console logging."; 953 uses selector; 954 } 955 container file { 956 if-feature file-action; 957 description 958 "This container describes the configuration parameters for 959 file logging. If file-archive limits are not supplied, it 960 is assumed that the local implementation defined limits 961 will be used."; 962 list log-file { 963 key "name"; 964 description 965 "This list describes a collection of local logging 966 files."; 967 leaf name { 968 type inet:uri { 969 pattern 'file:.*'; 970 } 971 description 972 "This leaf specifies the name of the log file which 973 MUST use the uri scheme file:."; 974 } 975 uses selector; 976 uses structured-data; 977 container file-rotation { 978 description 979 "This container describes the configuration 980 parameters for log file rotation."; 981 leaf number-of-files { 982 if-feature file-limit-size; 983 type uint32; 984 default 1; 985 description 986 "This leaf specifies the maximum number of log 987 files retained. Specify 1 for implementations 988 that only support one log file."; 989 } 990 leaf max-file-size { 991 if-feature file-limit-size; 992 type uint32; 993 units "megabytes"; 994 description 995 "This leaf specifies the maximum log file size."; 996 } 997 leaf rollover { 998 if-feature file-limit-duration; 999 type uint32; 1000 units "minutes"; 1001 description 1002 "This leaf specifies the length of time that log 1003 events should be written to a specific log file. 1004 Log events that arrive after the rollover period 1005 cause the current log file to be closed and a new 1006 log file to be opened."; 1007 } 1008 leaf retention { 1009 if-feature file-limit-duration; 1010 type uint32; 1011 units "hours"; 1012 description 1013 "This leaf specifies the length of time that 1014 completed/closed log event files should be stored 1015 in the file system before they are deleted."; 1016 } 1017 } 1018 } 1019 } 1020 container remote { 1021 if-feature remote-action; 1022 description 1023 "This container describes the configuration parameters 1024 for forwarding syslog messages to remote relays or 1025 collectors."; 1026 list destination { 1027 key "name"; 1028 description 1029 "This list describes a collection of remote logging 1030 destinations."; 1031 leaf name { 1032 type string; 1033 description 1034 "An arbitrary name for the endpoint to connect to."; 1035 } 1036 choice transport { 1037 mandatory true; 1038 description 1039 "This choice describes the transport option."; 1040 case tcp { 1041 container tcp { 1042 description 1043 "This container describes the TCP transport 1044 options."; 1045 reference 1046 "RFC 6587: Transmission of Syslog Messages over 1047 TCP"; 1048 leaf address { 1049 type inet:host; 1050 description 1051 "The leaf uniquely specifies the address of 1052 the remote host. One of the following must 1053 be specified: an ipv4 address, an ipv6 1054 address, or a host name."; 1055 } 1056 leaf port { 1057 type inet:port-number; 1058 default 514; 1059 description 1060 "This leaf specifies the port number used to 1061 deliver messages to the remote server."; 1062 } 1063 } 1064 } 1065 case udp { 1066 container udp { 1067 description 1068 "This container describes the UDP transport 1069 options."; 1070 reference 1071 "RFC 5426: Transmission of Syslog Messages over 1072 UDP"; 1073 leaf address { 1074 type inet:host; 1075 description 1076 "The leaf uniquely specifies the address of 1077 the remote host. One of the following must be 1078 specified: an ipv4 address, an ipv6 address, 1079 or a host name."; 1080 } 1081 leaf port { 1082 type inet:port-number; 1083 default 514; 1084 description 1085 "This leaf specifies the port number used to 1086 deliver messages to the remote server."; 1087 } 1088 } 1089 } 1090 case tls { 1091 container tls { 1092 description 1093 "This container describes the TLS transport 1094 options."; 1095 reference 1096 "RFC 5425: Transport Layer Security (TLS) 1097 Transport Mapping for Syslog "; 1098 leaf address { 1099 type inet:host; 1100 description 1101 "The leaf uniquely specifies the address of 1102 the remote host. One of the following must be 1103 specified: an ipv4 address, an ipv6 address, 1104 or a host name."; 1105 } 1106 leaf port { 1107 type inet:port-number; 1108 default 6514; 1109 description 1110 "TCP port 6514 has been allocated as the default 1111 port for syslog over TLS."; 1112 } 1113 uses tlsc:tls-client-grouping; 1114 } 1115 } 1116 } 1117 uses selector; 1118 uses structured-data; 1119 leaf facility-override { 1120 type identityref { 1121 base syslog-facility; 1122 } 1123 description 1124 "If specified, this leaf specifies the facility used 1125 to override the facility in messages delivered to 1126 the remote server."; 1127 } 1128 leaf source-interface { 1129 if-feature remote-source-interface; 1130 type if:interface-ref; 1131 description 1132 "This leaf sets the source interface to be used to 1133 send messages to the remote syslog server. If not 1134 set, messages sent to a remote syslog server will 1135 contain the IP address of the interface the syslog 1136 message uses to exit the network element"; 1137 } 1138 container signing-options { 1139 if-feature signed-messages; 1140 presence 1141 "If present, syslog-signing options is activated."; 1142 description 1143 "This container describes the configuration 1144 parameters for signed syslog messages."; 1145 reference 1146 "RFC 5848: Signed Syslog Messages"; 1147 container cert-signers { 1148 description 1149 "This container describes the signing certificate 1150 configuration for Signature Group 0 which covers 1151 the case for administrators who want all Signature 1152 Blocks to be sent to a single destination."; 1153 list cert-signer { 1154 key "name"; 1155 description 1156 "This list describes a collection of syslog 1157 message signers."; 1158 leaf name { 1159 type string; 1160 description 1161 "This leaf specifies the name of the syslog 1162 message signer."; 1163 } 1164 container certificate { 1165 uses ks:private-key-grouping; 1166 uses ks:certificate-grouping; 1167 description 1168 "This is the certificate that is periodically 1169 sent to the remote receiver. Selection of the 1170 certificate also implicitly selects the private 1171 key used to sign the syslog messages."; 1172 } 1173 leaf hash-algorithm { 1174 type enumeration { 1175 enum SHA1 { 1176 value 1; 1177 description 1178 "This enum describes the SHA1 algorithm."; 1179 } 1180 enum SHA256 { 1181 value 2; 1182 description 1183 "This enum describes the SHA256 algorithm."; 1184 } 1185 } 1186 description 1187 "This leaf describes the syslog signer hash 1188 algorithm used."; 1190 } 1191 } 1192 leaf cert-initial-repeat { 1193 type uint32; 1194 default 3; 1195 description 1196 "This leaf specifies the number of times each 1197 Certificate Block should be sent before the first 1198 message is sent."; 1199 } 1200 leaf cert-resend-delay { 1201 type uint32; 1202 units "seconds"; 1203 default 3600; 1204 description 1205 "This leaf specifies the maximum time delay in 1206 seconds until resending the Certificate Block."; 1207 } 1208 leaf cert-resend-count { 1209 type uint32; 1210 default 0; 1211 description 1212 "This leaf specifies the maximum number of other 1213 syslog messages to send until resending the 1214 Certificate Block."; 1215 } 1216 leaf sig-max-delay { 1217 type uint32; 1218 units "seconds"; 1219 default 60; 1220 description 1221 "This leaf specifies when to generate a new 1222 Signature Block. If this many seconds have 1223 elapsed since the message with the first message 1224 number of the Signature Block was sent, a new 1225 Signature Block should be generated."; 1226 } 1227 leaf sig-number-resends { 1228 type uint32; 1229 default 0; 1230 description 1231 "This leaf specifies the number of times a 1232 Signature Block is resent. (It is recommended to 1233 select a value of greater than 0 in particular 1234 when the UDP transport RFC 5426 is used.)."; 1235 } 1236 leaf sig-resend-delay { 1237 type uint32; 1238 units "seconds"; 1239 default 5; 1240 description 1241 "This leaf specifies when to send the next 1242 Signature Block transmission based on time. If 1243 this many seconds have elapsed since the previous 1244 sending of this Signature Block, resend it."; 1245 } 1246 leaf sig-resend-count { 1247 type uint32; 1248 default 0; 1249 description 1250 "This leaf specifies when to send the next 1251 Signature Block transmission based on a count. 1252 If this many other syslog messages have been 1253 sent since the previous sending of this 1254 Signature Block, resend it. A value of 0 means 1255 that you don't resend based on the number of 1256 messages."; 1257 } 1258 } 1259 } 1260 } 1261 } 1262 } 1263 } 1264 } 1265 1267 Figure 3. ietf-syslog Module 1269 5. Usage Examples 1270 Requirement: 1271 Enable console logging of syslogs of severity critical 1273 Here is the example syslog configuration xml: 1274 1276 1277 1278 1279 1280 all 1281 critical 1282 1283 1284 1285 1286 1288 Enable remote logging of syslogs to udp destination 1289 2001:db8:a0b:12f0::1 for facility auth, severity error 1291 1293 1294 1295 1296 remote1 1297 1298
foo.eample.com
1299 1300 1301 1302 auth 1303 error 1304 1305 1306 1307 1308 1309 1311 Figure 4. ietf-syslog Examples 1313 6. Acknowledgements 1315 The authors wish to thank the following who commented on this 1316 proposal: 1318 Andy Bierman 1320 Martin Bjorklund 1322 Alex Campbell 1323 Alex Clemm 1325 Jim Gibson 1327 Jeffrey Haas 1329 John Heasley 1331 Giles Heron 1333 Lisa Huang 1335 Mahesh Jethanandani 1337 Jeffrey K Lange 1339 Jan Lindblad 1341 Chris Lonvick 1343 Tom Petch 1345 Juergen Schoenwaelder 1347 Phil Shafer 1349 Jason Sterne 1351 Peter Van Horne 1353 Kent Watsen 1355 Bert Wijnen 1357 Dale R Worley 1359 Aleksandr Zhdankin 1361 7. IANA Considerations 1363 This document registers one URI in the IETF XML registry [RFC3688]. 1364 Following the format in [RFC3688], the following registration is 1365 requested: 1367 URI: urn:ietf:params:xml:ns:yang:ietf-syslog 1368 Registrant Contact: The NETCONF WG of the IETF. 1369 XML: N/A, the requested URI is an XML namespace. 1371 7.1. The YANG Module Names Registry 1373 This document registers one YANG module in the YANG Module Names 1374 registry [RFC7895]/>. Following the format in [RFC7950]/>, the the 1375 following registration is requested: 1377 name: ietf-syslog 1378 namespace: urn:ietf:params:xml:ns:yang:ietf-syslog 1379 prefix: ietf-syslog 1380 reference: RFC zzzz 1382 8. Security Considerations 1384 The YANG module defined in this document is designed to be accessed 1385 via YANG based management protocols, such as NETCONF [RFC6241] and 1386 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1387 implement secure transport layers (e.g., SSH, TLS) with mutual 1388 authentication. 1390 The NETCONF access control model (NACM) [RFC6536] provides the means 1391 to restrict access for particular users to a pre-configured subset of 1392 all available protocol operations and content. 1394 There are a number of data nodes defined in this YANG module that are 1395 writable/creatable/deletable (i.e., config true, which is the 1396 default). These data nodes may be considered sensitive or vulnerable 1397 in some network environments. Write operations (e.g., edit-config) 1398 to these data nodes without proper protection can have a negative 1399 effect on network operations. These are the subtrees and data nodes 1400 and their sensitivity/vulnerability: 1402 facility-filter/pattern-match: When writing this node, 1403 implementations MUST ensure that the regular expression pattern 1404 match is not constructed to cause a regular expression denial 1405 of service attack due to a pattern that causes the regular 1406 expression implementation to work very slowly (exponentially 1407 related to input size). 1409 Some of the readable data nodes in this YANG module may be considered 1410 sensitive or vulnerable in some network environments. It is thus 1411 important to control read access (e.g., via get, get-config, or 1412 notification) to these data nodes. 1414 There are no RPC operations defined in this YANG module. 1416 9. References 1418 9.1. Normative References 1420 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1421 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1422 RFC2119, March 1997, . 1425 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, DOI 1426 10.17487/RFC5424, March 2009, . 1429 [RFC5425] Miao, F., Ed., Ma, Y.Ed., and J. Salowey, Ed., "Transport 1430 Layer Security (TLS) Transport Mapping for Syslog", RFC 1431 5425, DOI 10.17487/RFC5425, March 2009, . 1434 [RFC5426] Okmianski, A., "Transmission of Syslog Messages over UDP", 1435 RFC 5426, DOI 10.17487/RFC5426, March 2009, . 1438 [RFC5848] Kelsey, J., Callas, J. and A. Clemm, "Signed Syslog 1439 Messages", RFC 5848, DOI 10.17487/RFC5848, May 2010, 1440 . 1442 [RFC6587] Gerhards, R. and C. Lonvick, "Transmission of Syslog 1443 Messages over TCP", RFC 6587, DOI 10.17487/RFC6587, April 1444 2012, . 1446 [RFC6691] Borman, D., "TCP Options and Maximum Segment Size (MSS)", 1447 RFC 6691, DOI 10.17487/RFC6691, July 2012, . 1450 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1451 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1452 . 1454 [RFC7895] Bierman, A., Bjorklund, M. and K. Watsen, "YANG Module 1455 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1456 . 1458 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1459 RFC 7950, DOI 10.17487/RFC7950, August 2016, . 1462 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1463 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1464 May 2017, . 1466 [Std-1003.1-2008] 1467 The Open Group, ""Chapter 9: Regular Expressions". The 1468 Open Group Base Specifications Issue 6, IEEE Std 1469 1003.1-2008, 2016 Edition.", September 2016, . 1472 [draft-ietf-netconf-keystore-04.txt] 1473 Juniper Networks, "YANG Data Model for a "Keystore" 1474 Mechanism draft-ietf-netconf-keystore-04", October 2017, 1475 . 1478 [draft-ietf-netconf-tls-client-server-05.txt] 1479 Juniper Networks, Cisco Systems, "YANG Groupings for TLS 1480 Clients and TLS Servers draft-ietf-netconf-tls-client- 1481 server-05", October 2017, . 1484 9.2. Informative References 1486 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1487 DOI 10.17487/RFC3688, January 2004, . 1490 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J.Ed., 1491 and A. Bierman, Ed., "Network Configuration Protocol 1492 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1493 . 1495 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1496 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 1497 10.17487/RFC6536, March 2012, . 1500 [RFC8040] Bierman, A., Bjorklund, M. and K. Watsen, "RESTCONF 1501 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1502 . 1504 Appendix A. Implementor Guidelines 1506 Appendix A.1. Extending Facilities 1508 Many vendors extend the list of facilities available for logging in 1509 their implementation. Additional facilities may not work with the 1510 syslog protocol as defined in [RFC5424] and hence such facilities 1511 apply for local syslog-like logging functionality. 1513 The following is an example that shows how additional facilities 1514 could be added to the list of available facilities (in this example 1515 two facilities are added): 1517 module vendor-syslog-types-example { 1518 namespace "urn:vendor:params:xml:ns:yang:vendor-syslog-types"; 1519 prefix vendor-syslogtypes; 1521 import ietf-syslog { 1522 prefix syslogtypes; 1523 } 1525 organization "Example, Inc."; 1526 contact 1527 "Example, Inc. 1528 Customer Service 1530 E-mail: syslog-yang@example.com"; 1532 description 1533 "This module contains a collection of vendor-specific YANG type 1534 definitions for SYSLOG."; 1536 revision 2017-08-11 { 1537 description 1538 "Version 1.0"; 1539 reference 1540 "Vendor SYSLOG Types: SYSLOG YANG Model"; 1541 } 1543 identity vendor_specific_type_1 { 1544 base syslogtypes:syslog-facility; 1545 description 1546 "Adding vendor specific type 1 to syslog-facility"; 1547 } 1549 identity vendor_specific_type_2 { 1550 base syslogtypes:syslog-facility; 1551 description 1552 "Adding vendor specific type 2 to syslog-facility"; 1553 } 1554 } 1556 Authors' Addresses 1558 Clyde Wildes, editor 1559 Cisco Systems Inc. 1560 170 West Tasman Drive 1561 San Jose, CA 95134 1562 US 1564 Phone: +1 408 527-2672 1565 Email: cwildes@cisco.com 1566 Kiran Koushik, editor 1567 Verizon Wireless 1568 500 W Dove Rd. 1569 Southlake, TX 76092 1570 US 1572 Phone: +1 512 650-0210 1573 Email: kirankoushik.agraharasreenivasa@verizonwireless.com