idnits 2.17.1 draft-ietf-netmod-syslog-model-26.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 15, 2018) is 2234 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) == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-04 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-05 ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 3 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: September 14, 2018 Verizon Wireless 6 March 15, 2018 8 A YANG Data Model for Syslog Configuration 9 draft-ietf-netmod-syslog-model-26 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 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 14, 2018. 34 Copyright Notice 36 Copyright (c) 2018 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Simplified BSD License text 45 as described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2 52 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.3. NDMA Compliance . . . . . . . . . . . . . . . . . . . . . 3 54 1.4. Editorial Note (To be removed by RFC Editor) . . . . . . . 3 55 2. Design of the Syslog Model . . . . . . . . . . . . . . . . . . 3 56 2.1. Syslog Module . . . . . . . . . . . . . . . . . . . . . . 5 57 3. Syslog YANG Module . . . . . . . . . . . . . . . . . . . . . . 7 58 3.1. The ietf-syslog Module . . . . . . . . . . . . . . . . . . 8 59 4. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . 25 60 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 62 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 26 63 6.2. The YANG Module Names Registry . . . . . . . . . . . . . . 26 64 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 65 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 66 8.1. Normative References . . . . . . . . . . . . . . . . . . . 27 67 8.2. Informative References . . . . . . . . . . . . . . . . . . 29 68 Appendix A. Implementer Guidelines . . . . . . . . . . . . . . . . 29 69 Appendix A.1. Extending Facilities . . . . . . . . . . . . . . 29 70 Appendix A.2. Syslog Terminal Output . . . . . . . . . . . . . 30 71 Appendix A.3. Syslog File Naming Convention . . . . . . . . . . 30 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 74 1. Introduction 76 This document defines a YANG [RFC7950] configuration data model that 77 may be used to configure the syslog feature running on a system. 78 YANG models can be used with network management protocols such as 79 NETCONF [RFC6241] to install, manipulate, and delete the 80 configuration of network devices. 82 The data model makes use of the YANG "feature" construct which allows 83 implementations to support only those syslog features that lie within 84 their capabilities. 86 This module can be used to configure the syslog application 87 conceptual layers as implemented on the target system. 89 Essentially, a syslog process receives messages (from the kernel, 90 processes, applications or other syslog processes) and processes 91 them. The processing may involve logging to a local file, and/or 92 displaying on console, and/or relaying to syslog processes on other 93 machines. The processing is determined by the "facility" that 94 originated the message and the "severity" assigned to the message by 95 the facility. 97 Such definitions of syslog protocol are defined in [RFC5424], and are 98 used in this RFC. 100 The YANG model in this document conforms to the Network Management 101 Datastore Architecture defined in [draft-ietf-netmod-revised- 102 datastores]. 104 1.1. Requirements Language 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in BCP 108 14 [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 1.2. Terminology 113 The term "originator" is defined in [RFC5424]: an "originator" 114 generates syslog content to be carried in a message. 116 The term "relay" is defined in [RFC5424]: a "relay" forwards 117 messages, accepting messages from originators or other relays and 118 sending them to collectors or other relays 120 The term "collectors" is defined in [RFC5424]: a "collector" gathers 121 syslog content for further analysis. 123 The term "action" refers to the processing that takes place for each 124 syslog message received. 126 1.3. NDMA Compliance 128 The YANG model in this document conforms to the Network Management 129 Datastore Architecture defined in I-D.ietf-netmod-revised-datastores 130 [I-D.ietf-netmod-revised-datastores]. 132 1.4. Editorial Note (To be removed by RFC Editor) 134 This document contains many placeholder values that need to be 135 replaced with finalized values at the time of publication. This note 136 summarizes all of the substitutions that are needed. No other RFC 137 Editor instructions are specified elsewhere in this document. 139 Artwork in this document contains shorthand references to drafts in 140 progress. Please apply the following replacements: 142 o "I-D.ietf-netconf-keystore" --> the assigned RFC value for draft- 143 ietf-netconf-keystore 145 o "I-D.ietf-netconf-tls-client-server" --> the assigned RFC value 146 for draft-ietf-netconf-tls-client-server 148 o "zzzz" --> the assigned RFC value for this draft 150 o I-D.ietf-netmod-revised-datastores --> the assigned RFC value for 151 draft-ietf-netmod-revised-datastores 153 2. Design of the Syslog Model 155 The syslog model was designed by comparing various syslog features 156 implemented by various vendors' in different implementations. 158 This document addresses the common leafs between implementations and 159 creates a common model, which can be augmented with proprietary 160 features, if necessary. This model is designed to be very simple for 161 maximum flexibility. 163 Some optional features are defined in this document to specify 164 functionality that is present in specific vendor configurations. 166 Syslog consists of originators and collectors. The following diagram 167 shows syslog messages flowing from originators, to collectors where 168 filtering can take place. 170 Originators 171 +-------------+ +-------------+ +-------------+ +-------------+ 172 | Various | | OS | | | | Remote | 173 | Components | | Kernel | | Line Cards | | Servers | 174 +-------------+ +-------------+ +-------------+ +-------------+ 176 +-------------+ +-------------+ +-------------+ +-------------+ 177 | SNMP | | Interface | | Standby | | Syslog | 178 | Events | | Events | | Supervisor | | Itself | 179 +-------------+ +-------------+ +-------------+ +-------------+ 181 | | 182 +----------------------------------------------------------------+ 183 | 184 | 185 | 186 | 187 +-------------+--------------+ 188 | | | 189 v v v 190 Collectors 191 +----------+ +----------+ +----------------+ 192 | | | Log | |Remote Relay(s)/| 193 | Console | | File(s) | |Collector(s) | 194 +----------+ +----------+ +----------------+ 196 Figure 1. Syslog Processing Flow 198 Collectors are configured using the leaves in the syslog model 199 "actions" container which correspond to each message collector: 201 console 203 log file(s) 205 remote relay(s)/collector(s) 207 Within each action, a selector is used to filter syslog messages. A 208 selector consists of a list of one or more filters specified by 209 facility-severity pairs, and, if supported via the select-match 210 feature, an optional regular expression pattern match that is 211 performed on the [RFC5424] field. 213 A syslog message is processed if: 215 There is an element of facility-list (F, S) where 216 the message facility matches F 217 and the message severity matches S 218 and/or the message text matches the regex pattern (if it 219 is present) 221 The facility is one of a specific syslog-facility, or all facilities. 223 The severity is one of type syslog-severity, all severities, or none. 224 None is a special case that can be used to disable a filter. When 225 filtering severity, the default comparison is that messages of the 226 specified severity and higher are selected to be logged. This is 227 shown in the model as "default equals-or-higher". This behavior can 228 be altered if the select-adv-compare feature is enabled to specify a 229 compare operation and an action. Compare operations are: "equals" to 230 select messages with this single severity, or "equals-or-higher" to 231 select messages of the specified severity and higher. Actions are 232 used to log the message or block the message from being logged. 234 Many vendors extend the list of facilities available for logging in 235 their implementation. An example is included in Extending Facilities 236 (Appendix A.1). 238 2.1. Syslog Module 240 A simplified graphical representation of the data model is used in 241 this document. Please see [I-D.ietf-netmod-yang-tree-diagrams] for 242 tree diagram notation. 244 module: ietf-syslog 245 +--rw syslog! 246 +--rw actions 247 +--rw console! {console-action}? 248 | +--rw facility-filter 249 | | +--rw facility-list* [facility severity] 250 | | +--rw facility union 251 | | +--rw severity union 252 | | +--rw advanced-compare {select-adv-compare}? 253 | | +--rw compare? enumeration 254 | | +--rw action? enumeration 255 | +--rw pattern-match? string {select-match}? 256 +--rw file {file-action}? 257 | +--rw log-file* [name] 258 | +--rw name inet:uri 259 | +--rw facility-filter 260 | | +--rw facility-list* [facility severity] 261 | | +--rw facility union 262 | | +--rw severity union 263 | | +--rw advanced-compare {select-adv-compare}? 264 | | +--rw compare? enumeration 265 | | +--rw action? enumeration 266 | +--rw pattern-match? string {select-match}? 267 | +--rw structured-data? boolean {structured-data}? 268 | +--rw file-rotation 269 | +--rw number-of-files? uint32 {file-limit-size}? 270 | +--rw max-file-size? uint32 {file-limit-size}? 271 | +--rw rollover? uint32 272 | | {file-limit-duration}? 273 | +--rw retention? uint32 274 | {file-limit-duration}? 275 +--rw remote {remote-action}? 276 +--rw destination* [name] 277 +--rw name string 278 +--rw (transport) 279 | +--:(udp) 280 | | +--rw udp 281 | | +--rw address? inet:host 282 | | +--rw port? inet:port-number 283 | +--:(tls) 284 | +--rw tls 285 | +--rw address? inet:host 286 | +--rw port? inet:port-number 287 | +--rw client-auth 288 | | +--rw (auth-type)? 289 | | +--:(certificate) 290 | | +--rw certificate? leafref 291 | +--rw server-auth 292 | | +--rw pinned-ca-certs? leafref 293 | | +--rw pinned-server-certs? leafref 294 | +--rw hello-params 295 | {tls-client-hello-params-config}? 296 | +--rw tls-versions 297 | | +--rw tls-version* identityref 298 | +--rw cipher-suites 299 | +--rw cipher-suite* identityref 300 +--rw facility-filter 301 | +--rw facility-list* [facility severity] 302 | +--rw facility union 303 | +--rw severity union 304 | +--rw advanced-compare {select-adv-compare}? 305 | +--rw compare? enumeration 306 | +--rw action? enumeration 307 +--rw pattern-match? string {select-match}? 308 +--rw structured-data? boolean {structured-data}? 309 +--rw facility-override? identityref 310 +--rw source-interface? if:interface-ref 311 | {remote-source-interface}? 312 +--rw signing! {signed-messages}? 313 +--rw cert-signers 314 +--rw cert-signer* [name] 315 | +--rw name string 316 | +--rw cert 317 | | +--rw algorithm? 318 | | | identityref 319 | | +--rw private-key? 320 | | | union 321 | | +--rw public-key? 322 | | | binary 323 | | +---x generate-private-key 324 | | | +---w input 325 | | | +---w algorithm? 326 | | | identityref 327 | | +--rw certificates 328 | | | +--rw certificate* [name] 329 | | | +--rw name string 330 | | | +--rw value? binary 331 | | +---x generate-certificate-signing-request 332 | | +---w input 333 | | | +---w subject binary 334 | | | +---w attributes? binary 335 | | +--ro output 336 | | +--ro certificate-signing-request 337 | | binary 338 | +--rw hash-algorithm? enumeration 339 +--rw cert-initial-repeat? uint32 340 +--rw cert-resend-delay? uint32 341 +--rw cert-resend-count? uint32 342 +--rw sig-max-delay? uint32 343 +--rw sig-number-resends? uint32 344 +--rw sig-resend-delay? uint32 345 +--rw sig-resend-count? uint32 347 Figure 2. ietf-syslog Module Tree 349 3. Syslog YANG Module 350 3.1. The ietf-syslog Module 352 This module imports typedefs from [RFC6991], 353 [I-D.ietf-netmod-rfc7223bis], groupings from 354 [I-D.ietf-netconf-keystore], and 355 [I-D.ietf-netconf-tls-client-server], and it references [RFC5424], 356 [RFC5425], [RFC5426], [RFC5848], [RFC8089], [RFC8174], and 357 [Std-1003.1-2008]. 359 file "ietf-syslog@2018-03-15.yang" 360 module ietf-syslog { 361 yang-version 1.1; 363 namespace "urn:ietf:params:xml:ns:yang:ietf-syslog"; 364 prefix syslog; 366 import ietf-inet-types { 367 prefix inet; 368 reference 369 "RFC 6991: Common YANG Data Types"; 370 } 372 import ietf-interfaces { 373 prefix if; 374 reference 375 "I-D.ietf-netmod-rfc7223bis: A YANG Data Model 376 for Interface Management"; 377 } 379 import ietf-tls-client { 380 prefix tlsc; 381 reference 382 "I-D.ietf-netconf-tls-client-server: 383 YANG Groupings for TLS Clients and TLS Servers"; 384 } 386 import ietf-keystore { 387 prefix ks; 388 reference 389 "I-D.ietf-netconf-keystore: YANG Data Model for a 390 Keystore Mechanism"; 391 } 393 organization 394 "IETF NETMOD (Network Modeling) Working Group"; 396 contact 397 "WG Web: 398 WG List: 400 Editor: Kiran Agrahara Sreenivasa 401 404 Editor: Clyde Wildes 405 "; 406 description 407 "This module contains a collection of YANG definitions 408 for syslog configuration. 410 Copyright (c) 2018 IETF Trust and the persons identified as 411 authors of the code. All rights reserved. 413 Redistribution and use in source and binary forms, with or 414 without modification, is permitted pursuant to, and subject to 415 the license terms contained in, the Simplified BSD License set 416 forth in Section 4.c of the IETF Trust's Legal Provisions 417 Relating to IETF Documents 418 (http://trustee.ietf.org/license-info). 420 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 421 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 422 'OPTIONAL' in the module text are to be interpreted as 423 described in RFC 2119 (http://tools.ietf.org/html/rfc2119). 425 This version of this YANG module is part of RFC zzzz 426 (http://tools.ietf.org/html/rfczzzz); see the RFC itself for 427 full legal notices."; 429 revision 2018-03-15 { 430 description 431 "Initial Revision"; 432 reference 433 "RFC zzzz: Syslog YANG Model"; 434 } 436 feature console-action { 437 description 438 "This feature indicates that the local console action is 439 supported."; 440 } 442 feature file-action { 443 description 444 "This feature indicates that the local file action is 445 supported."; 446 } 448 feature file-limit-size { 449 description 450 "This feature indicates that file logging resources 451 are managed using size and number limits."; 452 } 454 feature file-limit-duration { 455 description 456 "This feature indicates that file logging resources 457 are managed using time based limits."; 458 } 460 feature remote-action { 461 description 462 "This feature indicates that the remote server action is 463 supported."; 464 } 465 feature remote-source-interface { 466 description 467 "This feature indicates that source-interface is supported 468 supported for the remote-action."; 469 } 471 feature select-adv-compare { 472 description 473 "This feature represents the ability to select messages 474 using the additional comparison operators when comparing 475 the syslog message severity."; 476 } 478 feature select-match { 479 description 480 "This feature represents the ability to select messages 481 based on a Posix 1003.2 regular expression pattern match."; 482 } 484 feature structured-data { 485 description 486 "This feature represents the ability to log messages 487 in structured-data format."; 488 reference 489 "RFC 5424: The Syslog Protocol"; 490 } 492 feature signed-messages { 493 description 494 "This feature represents the ability to configure signed 495 syslog messages."; 496 reference 497 "RFC 5848: Signed Syslog Messages"; 498 } 500 typedef syslog-severity { 501 type enumeration { 502 enum "emergency" { 503 value 0; 504 description 505 "The severity level 'Emergency' indicating that the 506 system is unusable."; 507 } 508 enum "alert" { 509 value 1; 510 description 511 "The severity level 'Alert' indicating that an action 512 must be taken immediately."; 513 } 514 enum "critical" { 515 value 2; 516 description 517 "The severity level 'Critical' indicating a critical 518 condition."; 520 } 521 enum "error" { 522 value 3; 523 description 524 "The severity level 'Error' indicating an error 525 condition."; 526 } 527 enum "warning" { 528 value 4; 529 description 530 "The severity level 'Warning' indicating a warning 531 condition."; 532 } 533 enum "notice" { 534 value 5; 535 description 536 "The severity level 'Notice' indicating a normal but 537 significant condition."; 538 } 539 enum "info" { 540 value 6; 541 description 542 "The severity level 'Info' indicating an informational 543 message."; 544 } 545 enum "debug" { 546 value 7; 547 description 548 "The severity level 'Debug' indicating a debug-level 549 message."; 550 } 551 } 552 description 553 "The definitions for Syslog message severity. 554 Note that a lower value is a higher severity. Comparisons of 555 equal-or-higher severity mean equal or lower numeric value"; 556 reference 557 "RFC 5424: The Syslog Protocol"; 558 } 560 identity syslog-facility { 561 description 562 "This identity is used as a base for all syslog facilities."; 563 reference 564 "RFC 5424: The Syslog Protocol"; 565 } 567 identity kern { 568 base syslog-facility; 569 description 570 "The facility for kernel messages (0)."; 571 reference 572 "RFC 5424: The Syslog Protocol"; 573 } 574 identity user { 575 base syslog-facility; 576 description 577 "The facility for user-level messages (1)."; 578 reference 579 "RFC 5424: The Syslog Protocol"; 580 } 582 identity mail { 583 base syslog-facility; 584 description 585 "The facility for the mail system (2)."; 586 reference 587 "RFC 5424: The Syslog Protocol"; 588 } 590 identity daemon { 591 base syslog-facility; 592 description 593 "The facility for the system daemons (3)."; 594 reference 595 "RFC 5424: The Syslog Protocol"; 596 } 598 identity auth { 599 base syslog-facility; 600 description 601 "The facility for security/authorization messages (4)."; 602 reference 603 "RFC 5424: The Syslog Protocol"; 604 } 606 identity syslog { 607 base syslog-facility; 608 description 609 "The facility for messages generated internally by syslogd 610 facility (5)."; 611 reference 612 "RFC 5424: The Syslog Protocol"; 613 } 615 identity lpr { 616 base syslog-facility; 617 description 618 "The facility for the line printer subsystem (6)."; 619 reference 620 "RFC 5424: The Syslog Protocol"; 621 } 623 identity news { 624 base syslog-facility; 625 description 626 "The facility for the network news subsystem (7)."; 628 reference 629 "RFC 5424: The Syslog Protocol"; 630 } 632 identity uucp { 633 base syslog-facility; 634 description 635 "The facility for the UUCP subsystem (8)."; 636 reference 637 "RFC 5424: The Syslog Protocol"; 638 } 640 identity cron { 641 base syslog-facility; 642 description 643 "The facility for the clock daemon (9)."; 644 reference 645 "RFC 5424: The Syslog Protocol"; 646 } 648 identity authpriv { 649 base syslog-facility; 650 description 651 "The facility for privileged security/authorization messages 652 (10)."; 653 reference 654 "RFC 5424: The Syslog Protocol"; 655 } 657 identity ftp { 658 base syslog-facility; 659 description 660 "The facility for the FTP daemon (11)."; 661 reference 662 "RFC 5424: The Syslog Protocol"; 663 } 665 identity ntp { 666 base syslog-facility; 667 description 668 "The facility for the NTP subsystem (12)."; 669 reference 670 "RFC 5424: The Syslog Protocol"; 671 } 673 identity audit { 674 base syslog-facility; 675 description 676 "The facility for log audit messages (13)."; 677 reference 678 "RFC 5424: The Syslog Protocol"; 679 } 681 identity console { 682 base syslog-facility; 683 description 684 "The facility for log alert messages (14)."; 685 reference 686 "RFC 5424: The Syslog Protocol"; 687 } 689 identity cron2 { 690 base syslog-facility; 691 description 692 "The facility for the second clock daemon (15)."; 693 reference 694 "RFC 5424: The Syslog Protocol"; 695 } 697 identity local0 { 698 base syslog-facility; 699 description 700 "The facility for local use 0 messages (16)."; 701 reference 702 "RFC 5424: The Syslog Protocol"; 703 } 705 identity local1 { 706 base syslog-facility; 707 description 708 "The facility for local use 1 messages (17)."; 709 reference 710 "RFC 5424: The Syslog Protocol"; 711 } 713 identity local2 { 714 base syslog-facility; 715 description 716 "The facility for local use 2 messages (18)."; 717 reference 718 "RFC 5424: The Syslog Protocol"; 719 } 721 identity local3 { 722 base syslog-facility; 723 description 724 "The facility for local use 3 messages (19)."; 725 reference 726 "RFC 5424: The Syslog Protocol"; 727 } 729 identity local4 { 730 base syslog-facility; 731 description 732 "The facility for local use 4 messages (20)."; 733 reference 734 "RFC 5424: The Syslog Protocol"; 735 } 736 identity local5 { 737 base syslog-facility; 738 description 739 "The facility for local use 5 messages (21)."; 740 reference 741 "RFC 5424: The Syslog Protocol"; 742 } 744 identity local6 { 745 base syslog-facility; 746 description 747 "The facility for local use 6 messages (22)."; 748 reference 749 "RFC 5424: The Syslog Protocol"; 750 } 752 identity local7 { 753 base syslog-facility; 754 description 755 "The facility for local use 7 messages (23)."; 756 reference 757 "RFC 5424: The Syslog Protocol"; 758 } 760 grouping severity-filter { 761 description 762 "This grouping defines the processing used to select 763 log messages by comparing syslog message severity using 764 the following processing rules: 765 - if 'none', do not match. 766 - if 'all', match. 767 - else compare message severity with the specified severity 768 according to the default compare rule (all messages of the 769 specified severity and greater match) or if the 770 select-adv-compare feature is present, use the 771 advance-compare rule."; 772 leaf severity { 773 type union { 774 type syslog-severity; 775 type enumeration { 776 enum none { 777 value 2147483647; 778 description 779 "This enum describes the case where no severities 780 are selected."; 781 } 782 enum all { 783 value -2147483648; 784 description 785 "This enum describes the case where all severities 786 are selected."; 787 } 788 } 790 } 791 mandatory true; 792 description 793 "This leaf specifies the syslog message severity."; 794 } 795 container advanced-compare { 796 when '../severity != "all" and 797 ../severity != "none"' { 798 description 799 "The advanced compare container is not applicable for 800 severity 'all' or severity 'none'"; 801 } 802 if-feature select-adv-compare; 803 leaf compare { 804 type enumeration { 805 enum equals { 806 description 807 "This enum specifies that the severity comparison 808 operation will be equals."; 809 } 810 enum equals-or-higher { 811 description 812 "This enum specifies that the severity comparison 813 operation will be equals or higher."; 814 } 815 } 816 default equals-or-higher; 817 description 818 "The compare can be used to specify the comparison 819 operator that should be used to compare the syslog message 820 severity with the specified severity."; 821 } 822 leaf action { 823 type enumeration { 824 enum log { 825 description 826 "This enum specifies that if the compare operation is 827 true the message will be logged."; 828 } 829 enum block { 830 description 831 "This enum specifies that if the compare operation is 832 true the message will not be logged."; 833 } 834 } 835 default log; 836 description 837 "The action can be used to specify if the message should 838 be logged or blocked based on the outcome of the compare 839 operation."; 840 } 841 description 842 "This container describes additional severity compare 843 operations that can be used in place of the default 844 severity comparison. The compare leaf specifies the type of 845 the compare that is done and the action leaf specifies the 846 intended result. 847 Example: compare->equals and action->block means 848 messages that have a severity that are equal to the 849 specified severity will not be logged."; 850 } 851 } 853 grouping selector { 854 description 855 "This grouping defines a syslog selector which is used to 856 select log messages for the log-actions (console, file, 857 remote, etc.). Choose one or both of the following: 858 facility [ ...] 859 pattern-match regular-expression-match-string 860 If both facility and pattern-match are specified, both must 861 match in order for a log message to be selected."; 862 container facility-filter { 863 description 864 "This container describes the syslog filter parameters."; 865 list facility-list { 866 key "facility severity"; 867 ordered-by user; 868 description 869 "This list describes a collection of syslog 870 facilities and severities."; 871 leaf facility { 872 type union { 873 type identityref { 874 base syslog-facility; 875 } 876 type enumeration { 877 enum all { 878 description 879 "This enum describes the case where all 880 facilities are requested."; 881 } 882 } 883 } 884 description 885 "The leaf uniquely identifies a syslog facility."; 886 } 887 uses severity-filter; 888 } 889 } 890 leaf pattern-match { 891 if-feature select-match; 892 type string; 893 description 894 "This leaf describes a Posix 1003.2 regular expression 895 string that can be used to select a syslog message for 896 logging. The match is performed on the SYSLOG-MSG field."; 897 reference 898 "RFC 5424: The Syslog Protocol 899 Std-1003.1-2008 Regular Expressions"; 900 } 901 } 903 grouping structured-data { 904 description 905 "This grouping defines the syslog structured data option 906 which is used to select the format used to write log 907 messages."; 908 leaf structured-data { 909 if-feature structured-data; 910 type boolean; 911 default false; 912 description 913 "This leaf describes how log messages are written. 914 If true, messages will be written with one or more 915 STRUCTURED-DATA elements; if false, messages will be 916 written with STRUCTURED-DATA = NILVALUE."; 917 reference 918 "RFC 5424: The Syslog Protocol"; 919 } 920 } 922 container syslog { 923 presence "Enables logging."; 924 description 925 "This container describes the configuration parameters for 926 syslog."; 927 container actions { 928 description 929 "This container describes the log-action parameters 930 for syslog."; 931 container console { 932 if-feature console-action; 933 presence "Enables logging to the console"; 934 description 935 "This container describes the configuration parameters 936 for console logging."; 937 uses selector; 938 } 939 container file { 940 if-feature file-action; 941 description 942 "This container describes the configuration parameters for 943 file logging. If file-archive limits are not supplied, it 944 is assumed that the local implementation defined limits 945 will be used."; 946 list log-file { 947 key "name"; 948 description 949 "This list describes a collection of local logging 950 files."; 951 leaf name { 952 type inet:uri { 953 pattern 'file:.*'; 954 } 955 description 956 "This leaf specifies the name of the log file which 957 MUST use the uri scheme file:."; 958 reference 959 "RFC 8089: The file URI Scheme"; 960 } 961 uses selector; 962 uses structured-data; 963 container file-rotation { 964 description 965 "This container describes the configuration 966 parameters for log file rotation."; 967 leaf number-of-files { 968 if-feature file-limit-size; 969 type uint32; 970 default 1; 971 description 972 "This leaf specifies the maximum number of log 973 files retained. Specify 1 for implementations 974 that only support one log file."; 975 } 976 leaf max-file-size { 977 if-feature file-limit-size; 978 type uint32; 979 units "megabytes"; 980 description 981 "This leaf specifies the maximum log file size."; 982 } 983 leaf rollover { 984 if-feature file-limit-duration; 985 type uint32; 986 units "minutes"; 987 description 988 "This leaf specifies the length of time that log 989 events should be written to a specific log file. 990 Log events that arrive after the rollover period 991 cause the current log file to be closed and a new 992 log file to be opened."; 993 } 994 leaf retention { 995 if-feature file-limit-duration; 996 type uint32; 997 units "minutes"; 998 description 999 "This leaf specifies the length of time that 1000 completed/closed log event files should be stored 1001 in the file system before they are removed."; 1002 } 1003 } 1004 } 1005 } 1006 container remote { 1007 if-feature remote-action; 1008 description 1009 "This container describes the configuration parameters 1010 for forwarding syslog messages to remote relays or 1011 collectors."; 1012 list destination { 1013 key "name"; 1014 description 1015 "This list describes a collection of remote logging 1016 destinations."; 1017 leaf name { 1018 type string; 1019 description 1020 "An arbitrary name for the endpoint to connect to."; 1021 } 1022 choice transport { 1023 mandatory true; 1024 description 1025 "This choice describes the transport option."; 1026 case udp { 1027 container udp { 1028 description 1029 "This container describes the UDP transport 1030 options."; 1031 reference 1032 "RFC 5426: Transmission of Syslog Messages over 1033 UDP"; 1034 leaf address { 1035 type inet:host; 1036 description 1037 "The leaf uniquely specifies the address of 1038 the remote host. One of the following must be 1039 specified: an ipv4 address, an ipv6 address, 1040 or a host name."; 1041 } 1042 leaf port { 1043 type inet:port-number; 1044 default 514; 1045 description 1046 "This leaf specifies the port number used to 1047 deliver messages to the remote server."; 1048 } 1049 } 1050 } 1051 case tls { 1052 container tls { 1053 description 1054 "This container describes the TLS transport 1055 options."; 1056 reference 1057 "RFC 5425: Transport Layer Security (TLS) 1058 Transport Mapping for Syslog "; 1059 leaf address { 1060 type inet:host; 1061 description 1062 "The leaf uniquely specifies the address of 1063 the remote host. One of the following must be 1064 specified: an ipv4 address, an ipv6 address, 1065 or a host name."; 1066 } 1067 leaf port { 1068 type inet:port-number; 1069 default 6514; 1070 description 1071 "TCP port 6514 has been allocated as the default 1072 port for syslog over TLS."; 1073 } 1074 uses tlsc:tls-client-grouping; 1075 } 1076 } 1077 } 1078 uses selector; 1079 uses structured-data; 1080 leaf facility-override { 1081 type identityref { 1082 base syslog-facility; 1083 } 1084 description 1085 "If specified, this leaf specifies the facility used 1086 to override the facility in messages delivered to 1087 the remote server."; 1088 } 1089 leaf source-interface { 1090 if-feature remote-source-interface; 1091 type if:interface-ref; 1092 description 1093 "This leaf sets the source interface to be used to 1094 send messages to the remote syslog server. If not 1095 set, messages can be sent on any interface."; 1096 } 1097 container signing { 1098 if-feature signed-messages; 1099 presence 1100 "If present, syslog-signing options is activated."; 1101 description 1102 "This container describes the configuration 1103 parameters for signed syslog messages."; 1104 reference 1105 "RFC 5848: Signed Syslog Messages"; 1106 container cert-signers { 1107 description 1108 "This container describes the signing certificate 1109 configuration for Signature Group 0 which covers 1110 the case for administrators who want all Signature 1111 Blocks to be sent to a single destination."; 1112 list cert-signer { 1113 key "name"; 1114 description 1115 "This list describes a collection of syslog 1116 message signers."; 1117 leaf name { 1118 type string; 1119 description 1120 "This leaf specifies the name of the syslog 1121 message signer."; 1122 } 1123 container cert { 1124 uses ks:private-key-grouping; 1125 uses ks:certificate-grouping; 1126 description 1127 "This is the certificate that is periodically 1128 sent to the remote receiver. Selection of the 1129 certificate also implicitly selects the private 1130 key used to sign the syslog messages."; 1131 } 1132 leaf hash-algorithm { 1133 type enumeration { 1134 enum SHA1 { 1135 value 1; 1136 description 1137 "This enum describes the SHA1 algorithm."; 1138 } 1139 enum SHA256 { 1140 value 2; 1141 description 1142 "This enum describes the SHA256 algorithm."; 1143 } 1144 } 1145 description 1146 "This leaf describes the syslog signer hash 1147 algorithm used."; 1148 } 1149 } 1150 leaf cert-initial-repeat { 1151 type uint32; 1152 default 3; 1153 description 1154 "This leaf specifies the number of times each 1155 Certificate Block should be sent before the first 1156 message is sent."; 1157 } 1158 leaf cert-resend-delay { 1159 type uint32; 1160 units "seconds"; 1161 default 3600; 1162 description 1163 "This leaf specifies the maximum time delay in 1164 seconds until resending the Certificate Block."; 1165 } 1166 leaf cert-resend-count { 1167 type uint32; 1168 default 0; 1169 description 1170 "This leaf specifies the maximum number of other 1171 syslog messages to send until resending the 1172 Certificate Block."; 1173 } 1174 leaf sig-max-delay { 1175 type uint32; 1176 units "seconds"; 1177 default 60; 1178 description 1179 "This leaf specifies when to generate a new 1180 Signature Block. If this many seconds have 1181 elapsed since the message with the first message 1182 number of the Signature Block was sent, a new 1183 Signature Block should be generated."; 1184 } 1185 leaf sig-number-resends { 1186 type uint32; 1187 default 0; 1188 description 1189 "This leaf specifies the number of times a 1190 Signature Block is resent. (It is recommended to 1191 select a value of greater than 0 in particular 1192 when the UDP transport RFC 5426 is used.)."; 1193 } 1194 leaf sig-resend-delay { 1195 type uint32; 1196 units "seconds"; 1197 default 5; 1198 description 1199 "This leaf specifies when to send the next 1200 Signature Block transmission based on time. If 1201 this many seconds have elapsed since the previous 1202 sending of this Signature Block, resend it."; 1203 } 1204 leaf sig-resend-count { 1205 type uint32; 1206 default 0; 1207 description 1208 "This leaf specifies when to send the next 1209 Signature Block transmission based on a count. 1210 If this many other syslog messages have been 1211 sent since the previous sending of this 1212 Signature Block, resend it. A value of 0 means 1213 that you don't resend based on the number of 1214 messages."; 1215 } 1216 } 1217 } 1218 } 1219 } 1220 } 1221 } 1223 } 1224 1226 Figure 3. ietf-syslog Module 1228 4. Usage Examples 1230 Requirement: 1231 Enable console logging of syslogs of severity critical 1233 1234 1235 1236 1237 1238 all 1239 critical 1240 1241 1242 1243 1244 1246 Enable remote logging of syslogs to udp destination 1247 foo.example.com for facility auth, severity error 1249 1250 1251 1252 1253 remote1 1254 1255
foo.example.com
1256 1257 1258 1259 auth 1260 error 1261 1262 1263 1264 1265 1266 1268 Figure 4. ietf-syslog Examples 1270 5. Acknowledgements 1272 The authors wish to thank the following who commented on this 1273 proposal: 1275 Andy Bierman, Martin Bjorklund, Alex Campbell, Alex Clemm, Francis 1276 Dupont, Jim Gibson, Jeffrey Haas, Bob Harold, John Heasley, Giles 1277 Heron, Lisa Huang, Mahesh Jethanandani, Warren Kumari, Jeffrey K 1278 Lange, Jan Lindblad, Chris Lonvick, Alexey Melnikov, Kathleen 1279 Moriarty, Tom Petch, Adam Roach, Juergen Schoenwaelder, Phil Shafer, 1280 Yaron Sheffer, Jason Sterne, Peter Van Horne, Kent Watsen, Bert 1281 Wijnen, Dale R Worley, and Aleksandr Zhdankin. 1283 6. IANA Considerations 1285 6.1. The IETF XML Registry 1287 This document registers one URI in the IETF XML registry [RFC3688]. 1288 Following the format in [RFC3688], the following registration is 1289 requested: 1291 URI: urn:ietf:params:xml:ns:yang:ietf-syslog 1292 Registrant Contact: The IESG. 1293 XML: N/A, the requested URI is an XML namespace. 1295 6.2. The YANG Module Names Registry 1297 This document registers one YANG module in the YANG Module Names 1298 registry [RFC7895]. Following the format in [RFC7950], the following 1299 registration is requested: 1301 name: ietf-syslog 1302 namespace: urn:ietf:params:xml:ns:yang:ietf-syslog 1303 prefix: ietf-syslog 1304 reference: RFC zzzz 1306 7. Security Considerations 1308 The YANG module defined in this document is designed to be accessed 1309 via YANG based management protocols, such as NETCONF [RFC6241] and 1310 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1311 implement secure transport layers (e.g., SSH, TLS) with mutual 1312 authentication. 1314 The NETCONF access control model (NACM) [RFC6536] provides the means 1315 to restrict access for particular users to a pre-configured subset of 1316 all available protocol operations and content. 1318 There are a number of data nodes defined in this YANG module that are 1319 writable/creatable/deletable (i.e., config true, which is the 1320 default). These data nodes should be considered sensitive or 1321 vulnerable in all network environments. Logging in particular is 1322 used to assess the state of systems and can be used to indicate a 1323 network compromise. If logging were to be disabled through malicious 1324 means, attacks may not be readily detectable. Therefore write 1325 operations (e.g., edit-config) to these data nodes without proper 1326 protection can have a negative effect on network operations and on 1327 network security. 1329 In addition there are data nodes that require careful analysis and 1330 review. These are the subtrees and data nodes and their sensitivity/ 1331 vulnerability: 1333 facility-filter/pattern-match: When writing this node, 1334 implementations MUST ensure that the regular expression pattern 1335 match is not constructed to cause a regular expression denial 1336 of service attack due to a pattern that causes the regular 1337 expression implementation to work very slowly (exponentially 1338 related to input size). 1340 remote/destination/signing/cert-signer: When writing this subtree, 1341 implementations MUST NOT specify a private key that is used for 1342 any other purpose. 1344 Some of the readable data nodes in this YANG module may be considered 1345 sensitive or vulnerable in some network environments. It is thus 1346 important to control read access (e.g., via get, get-config, or 1347 notification) to these data nodes. These are the subtrees and data 1348 nodes and their sensitivity/vulnerability: 1350 remote/destination/transport: This subtree contains information 1351 about other hosts in the network, and the TLS transport 1352 certificate properties if TLS is selected as the transport 1353 protocol. 1355 remote/destination/signing: This subtree contains information 1356 about the syslog message signing properties including signing 1357 certificate information. 1359 There are no RPC operations defined in this YANG module. 1361 8. References 1363 8.1. Normative References 1365 [I-D.ietf-netconf-keystore] 1366 Watsen, K., "YANG Data Model for a "Keystore" Mechanism", 1367 Internet-Draft draft-ietf-netconf-keystore-04, October 1368 2017. 1370 [I-D.ietf-netconf-tls-client-server] 1371 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 1372 TLS Servers", Internet-Draft draft-ietf-netconf-tls- 1373 client-server-05, October 2017. 1375 [I-D.ietf-netmod-rfc7223bis] 1376 Bjorklund, M., "A YANG Data Model for Interface 1377 Management", Internet-Draft draft-ietf-netmod- 1378 rfc7223bis-03, January 2018. 1380 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1381 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1382 RFC2119, March 1997, . 1385 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, DOI 1386 10.17487/RFC5424, March 2009, . 1389 [RFC5425] Miao, F., Ed., Ma, Y.Ed., and J. Salowey, Ed., "Transport 1390 Layer Security (TLS) Transport Mapping for Syslog", RFC 1391 5425, DOI 10.17487/RFC5425, March 2009, . 1394 [RFC5426] Okmianski, A., "Transmission of Syslog Messages over UDP", 1395 RFC 5426, DOI 10.17487/RFC5426, March 2009, . 1398 [RFC5848] Kelsey, J., Callas, J. and A. Clemm, "Signed Syslog 1399 Messages", RFC 5848, DOI 10.17487/RFC5848, May 2010, 1400 . 1402 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 1403 6991, DOI 10.17487/RFC6991, July 2013, . 1406 [RFC7895] Bierman, A., Bjorklund, M. and K. Watsen, "YANG Module 1407 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1408 . 1410 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1411 RFC 7950, DOI 10.17487/RFC7950, August 2016, . 1414 [RFC8089] Kerwin, M., "The "file" URI Scheme", RFC 8089, DOI 1415 10.17487/RFC8089, February 2017, . 1418 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1419 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1420 May 2017, . 1422 [Std-1003.1-2008] 1423 The Open Group, ""Chapter 9: Regular Expressions". The 1424 Open Group Base Specifications Issue 6, IEEE Std 1425 1003.1-2008, 2016 Edition.", September 2016, . 1428 8.2. Informative References 1430 [I-D.ietf-netmod-revised-datastores] 1431 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K. 1432 and R. Wilton, "Network Management Datastore 1433 Architecture", Internet-Draft draft-ietf-netmod-revised- 1434 datastores-10, January 2018. 1436 [I-D.ietf-netmod-yang-tree-diagrams] 1437 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 1438 Internet-Draft draft-ietf-netmod-yang-tree-diagrams-06, 1439 February 2018. 1441 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1442 DOI 10.17487/RFC3688, January 2004, . 1445 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J.Ed., 1446 and A. Bierman, Ed., "Network Configuration Protocol 1447 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1448 . 1450 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1451 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 1452 10.17487/RFC6536, March 2012, . 1455 [RFC8040] Bierman, A., Bjorklund, M. and K. Watsen, "RESTCONF 1456 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1457 . 1459 Appendix A. Implementer Guidelines 1461 Appendix A.1. Extending Facilities 1463 Many vendors extend the list of facilities available for logging in 1464 their implementation. Additional facilities may not work with the 1465 syslog protocol as defined in [RFC5424] and hence such facilities 1466 apply for local syslog-like logging functionality. 1468 The following is an example that shows how additional facilities 1469 could be added to the list of available facilities (in this example 1470 two facilities are added): 1472 module example-vendor-syslog-types { 1473 namespace "http://example.com/ns/vendor-syslog-types"; 1474 prefix vendor-syslogtypes; 1476 import ietf-syslog { 1477 prefix syslogtypes; 1478 } 1480 organization "Example, Inc."; 1481 contact 1482 "Example, Inc. 1483 Customer Service 1485 E-mail: syslog-yang@example.com"; 1487 description 1488 "This module contains a collection of vendor-specific YANG type 1489 definitions for SYSLOG."; 1491 revision 2017-08-11 { 1492 description 1493 "Version 1.0"; 1494 reference 1495 "Vendor SYSLOG Types: SYSLOG YANG Model"; 1496 } 1498 identity vendor_specific_type_1 { 1499 base syslogtypes:syslog-facility; 1500 description 1501 "Adding vendor specific type 1 to syslog-facility"; 1502 } 1504 identity vendor_specific_type_2 { 1505 base syslogtypes:syslog-facility; 1506 description 1507 "Adding vendor specific type 2 to syslog-facility"; 1508 } 1509 } 1511 Appendix A.2. Syslog Terminal Output 1513 Terminal output with requirements more complex than the console 1514 subtree currently provides, are expected to be supported via vendor 1515 extensions rather than handled via the file subtree. 1517 Appendix A.3. Syslog File Naming Convention 1519 The syslog/file/log-file/file-rotation container contains 1520 configuration parameters for syslog file rotation. This section 1521 describes how these fields might be used by an implementer to name 1522 syslog files in a rotation process. This information is offered as 1523 an informative guide only. 1525 When an active syslog file with a name specified by log-file/name, 1526 reaches log-file/max-file-size and/or syslog events arrive after the 1527 period specified by log-file/rollover, the logging system can close 1528 the file, can compress it, and can name the archive file .0.gz. The logging system can then open a new active syslog 1530 file . 1532 When the new syslog file reaches either of the size limits referenced 1533 above, .0.gz can be renamed .1.gz and 1534 the new syslog file can be closed, compressed and renamed .0.gz. Each time that a new syslog file is closed, each of the 1536 prior syslog archive files named ..gz can be 1537 renamed to ..gz. 1539 Removal of archive log files could occur when either or both: 1541 - log-file/number-of-files specified - the logging system can create 1542 up to log-file/number-of-files syslog archive files after which, the 1543 contents of the oldest archived file could be overwritten. 1545 - log-file/retention specified - the logging system can remove those 1546 syslog archive files whose file expiration time (file creation time 1547 plus the specified log-file/retention time) is prior to the current 1548 time. 1550 Authors' Addresses 1552 Clyde Wildes, editor 1553 Cisco Systems Inc. 1554 170 West Tasman Drive 1555 San Jose, CA 95134 1556 US 1558 Phone: +1 408 527-2672 1559 Email: cwildes@cisco.com 1561 Kiran Koushik, editor 1562 Verizon Wireless 1563 500 W Dove Rd. 1564 Southlake, TX 76092 1565 US 1567 Phone: +1 512 650-0210 1568 Email: kirankoushik.agraharasreenivasa@verizonwireless.com