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