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