idnits 2.17.1 draft-ietf-netmod-syslog-model-24.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 08, 2018) is 2241 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: September 07, 2018 Verizon Wireless 6 March 08, 2018 8 A YANG Data Model for Syslog Configuration 9 draft-ietf-netmod-syslog-model-24 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 07, 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. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Design of the Syslog Model . . . . . . . . . . . . . . . . . . 4 60 3.1. Syslog Module . . . . . . . . . . . . . . . . . . . . . . 5 61 4. Syslog YANG Module . . . . . . . . . . . . . . . . . . . . . . 7 62 4.1. The ietf-syslog Module . . . . . . . . . . . . . . . . . . 8 63 5. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . 25 64 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25 65 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 66 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 26 67 7.2. The YANG Module Names Registry . . . . . . . . . . . . . . 26 68 8. Security Considerations . . . . . . . . . . . . . . . . . . . 26 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 70 9.1. Normative References . . . . . . . . . . . . . . . . . . . 27 71 9.2. Informative References . . . . . . . . . . . . . . . . . . 28 72 Appendix A. Implementor Guidelines . . . . . . . . . . . . . . . . 29 73 Appendix A.1. Extending Facilities . . . . . . . . . . . . . . 29 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 76 1. Introduction 78 Operating systems, processes and applications generate messages 79 indicating their own status or the occurrence of events. These 80 messages are useful for managing and/or debugging the network and its 81 services. The BSD syslog protocol is a widely adopted protocol that 82 is used for transmission and processing of the message. 84 Since each process, application and operating system was written 85 somewhat independently, there is little uniformity to the content of 86 syslog messages. For this reason, no assumption is made upon the 87 formatting or contents of the messages. The protocol is simply 88 designed to transport these event messages. No acknowledgment of the 89 receipt is made. 91 Essentially, a syslog process receives messages (from the kernel, 92 processes, applications or other syslog processes) and processes 93 them. The processing may involve logging to a local file, and/or 94 displaying on console, and/or relaying to syslog processes on other 95 machines. The processing is determined by the "facility" that 96 originated the message and the "severity" assigned to the message by 97 the facility. 99 We are using definitions of syslog protocol from [RFC5424] in this 100 RFC. 102 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. Problem Statement 154 This document defines a YANG [RFC7950] configuration data model that 155 may be used to configure the syslog feature running on a system. 156 YANG models can be used with network management protocols such as 157 NETCONF [RFC6241] to install, manipulate, and delete the 158 configuration of network devices. 160 The data model makes use of the YANG "feature" construct which allows 161 implementations to support only those syslog features that lie within 162 their capabilities. 164 This module can be used to configure the syslog application 165 conceptual layers as implemented on the target system. 167 3. Design of the Syslog Model 169 The syslog model was designed by comparing various syslog features 170 implemented by various vendors' in different implementations. 172 This document addresses the common leafs between implementations and 173 creates a common model, which can be augmented with proprietary 174 features, if necessary. This model is designed to be very simple for 175 maximum flexibility. 177 Some optional features are defined in this document to specify 178 functionality that is present in specific vendor configurations. 180 Syslog consists of originators and collectors. The following diagram 181 shows syslog messages flowing from originators, to collectors where 182 filtering can take place. 184 Originators 185 +-------------+ +-------------+ +-------------+ +-------------+ 186 | Various | | OS | | | | Remote | 187 | Components | | Kernel | | Line Cards | | Servers | 188 +-------------+ +-------------+ +-------------+ +-------------+ 190 +-------------+ +-------------+ +-------------+ +-------------+ 191 | SNMP | | Interface | | Standby | | Syslog | 192 | Events | | Events | | Supervisor | | Itself | 193 +-------------+ +-------------+ +-------------+ +-------------+ 195 | | 196 +----------------------------------------------------------------+ 197 | 198 | 199 | 200 | 201 +-------------+--------------+ 202 | | | 203 v v v 205 Collectors 206 +----------+ +----------+ +----------------+ 207 | | | Log | |Remote Relay(s)/| 208 | Console | | File(s) | |Collector(s) | 209 +----------+ +----------+ +----------------+ 211 Figure 1. Syslog Processing Flow 213 Collectors are configured using the leaves in the syslog model 214 "actions" container which correspond to each message collector: 216 console 218 log file(s) 220 remote relay(s)/collector(s) 222 Within each action, a selector is used to filter syslog messages. A 223 selector consists of a list of one or more filters specified by 224 facility-severity pairs, and, if supported via the select-match 225 feature, an optional regular expression pattern match that is 226 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, and [RFC8089] for URI 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 365 4.1. The ietf-syslog Module 367 This module imports typedefs from [RFC7223], groupings from 368 [I-D.ietf-netconf-keystore], 369 and [I-D.ietf-netconf-tls-client-server], and it references 370 [RFC5424], [RFC5425], [RFC5426], [RFC5848], and [RFC8174], and 371 [Std-1003.1-2008]. 373 file "ietf-syslog@2018-03-08.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-03-08 { 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."; 470 } 472 feature remote-action { 473 description 474 "This feature indicates that the remote server action is 475 supported."; 476 } 478 feature remote-source-interface { 479 description 480 "This feature indicates that source-interface is supported 481 supported for the remote-action."; 482 } 484 feature select-adv-compare { 485 description 486 "This feature represents the ability to select messages 487 using the additional comparison operators when comparing 488 the syslog message severity."; 489 } 491 feature select-match { 492 description 493 "This feature represents the ability to select messages 494 based on a Posix 1003.2 regular expression pattern match."; 495 } 497 feature structured-data { 498 description 499 "This feature represents the ability to log messages 500 in structured-data format."; 501 reference 502 "RFC 5424: The Syslog Protocol"; 503 } 505 feature signed-messages { 506 description 507 "This feature represents the ability to configure signed 508 syslog messages."; 509 reference 510 "RFC 5848: Signed Syslog Messages"; 511 } 513 typedef syslog-severity { 514 type enumeration { 515 enum "emergency" { 516 value 0; 517 description 518 "The severity level 'Emergency' indicating that the 519 system is unusable."; 520 } 521 enum "alert" { 522 value 1; 523 description 524 "The severity level 'Alert' indicating that an action 525 must be taken immediately."; 526 } 527 enum "critical" { 528 value 2; 529 description 530 "The severity level 'Critical' indicating a critical 531 condition."; 532 } 533 enum "error" { 534 value 3; 535 description 536 "The severity level 'Error' indicating an error 537 condition."; 538 } 539 enum "warning" { 540 value 4; 541 description 542 "The severity level 'Warning' indicating a warning 543 condition."; 544 } 545 enum "notice" { 546 value 5; 547 description 548 "The severity level 'Notice' indicating a normal but 549 significant condition."; 550 } 551 enum "info" { 552 value 6; 553 description 554 "The severity level 'Info' indicating an informational 555 message."; 556 } 557 enum "debug" { 558 value 7; 559 description 560 "The severity level 'Debug' indicating a debug-level 561 message."; 562 } 563 } 564 description 565 "The definitions for Syslog message severity. 566 Note that a lower value is a higher severity. Comparisons of 567 equal-or-higher severity mean equal or lower numeric value"; 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"; 643 } 645 identity uucp { 646 base syslog-facility; 647 description 648 "The facility for the UUCP subsystem (8)."; 649 reference 650 "RFC 5424: The Syslog Protocol"; 651 } 653 identity cron { 654 base syslog-facility; 655 description 656 "The facility for the clock daemon (9)."; 657 reference 658 "RFC 5424: The Syslog Protocol"; 659 } 661 identity authpriv { 662 base syslog-facility; 663 description 664 "The facility for privileged security/authorization messages 665 (10)."; 666 reference 667 "RFC 5424: The Syslog Protocol"; 668 } 670 identity ftp { 671 base syslog-facility; 672 description 673 "The facility for the FTP daemon (11)."; 674 reference 675 "RFC 5424: The Syslog Protocol"; 676 } 678 identity ntp { 679 base syslog-facility; 680 description 681 "The facility for the NTP subsystem (12)."; 682 reference 683 "RFC 5424: The Syslog Protocol"; 684 } 686 identity audit { 687 base syslog-facility; 688 description 689 "The facility for log audit messages (13)."; 690 reference 691 "RFC 5424: The Syslog Protocol"; 692 } 694 identity console { 695 base syslog-facility; 696 description 697 "The facility for log alert messages (14)."; 698 reference 699 "RFC 5424: The Syslog Protocol"; 700 } 702 identity cron2 { 703 base syslog-facility; 704 description 705 "The facility for the second clock daemon (15)."; 706 reference 707 "RFC 5424: The Syslog Protocol"; 708 } 710 identity local0 { 711 base syslog-facility; 712 description 713 "The facility for local use 0 messages (16)."; 714 reference 715 "RFC 5424: The Syslog Protocol"; 716 } 718 identity local1 { 719 base syslog-facility; 720 description 721 "The facility for local use 1 messages (17)."; 722 reference 723 "RFC 5424: The Syslog Protocol"; 724 } 726 identity local2 { 727 base syslog-facility; 728 description 729 "The facility for local use 2 messages (18)."; 730 reference 731 "RFC 5424: The Syslog Protocol"; 732 } 734 identity local3 { 735 base syslog-facility; 736 description 737 "The facility for local use 3 messages (19)."; 738 reference 739 "RFC 5424: The Syslog Protocol"; 740 } 742 identity local4 { 743 base syslog-facility; 744 description 745 "The facility for local use 4 messages (20)."; 746 reference 747 "RFC 5424: The Syslog Protocol"; 748 } 750 identity local5 { 751 base syslog-facility; 752 description 753 "The facility for local use 5 messages (21)."; 754 reference 755 "RFC 5424: The Syslog Protocol"; 756 } 758 identity local6 { 759 base syslog-facility; 760 description 761 "The facility for local use 6 messages (22)."; 762 reference 763 "RFC 5424: The Syslog Protocol"; 764 } 766 identity local7 { 767 base syslog-facility; 768 description 769 "The facility for local use 7 messages (23)."; 770 reference 771 "RFC 5424: The Syslog Protocol"; 772 } 774 grouping severity-filter { 775 description 776 "This grouping defines the processing used to select 777 log messages by comparing syslog message severity using 778 the following processing rules: 779 - if 'none', do not match. 780 - if 'all', match. 781 - else compare message severity with the specified severity 782 according to the default compare rule (all messages of the 783 specified severity and greater match) or if the 784 select-adv-compare feature is present, the advance-compare 785 rule."; 786 leaf severity { 787 type union { 788 type syslog-severity; 789 type enumeration { 790 enum none { 791 value 2147483647; 792 description 793 "This enum describes the case where no severities 794 are selected."; 795 } 796 enum all { 797 value -2147483648; 798 description 799 "This enum describes the case where all severities 800 are selected."; 801 } 802 } 803 } 804 mandatory true; 805 description 806 "This leaf specifies the syslog message severity."; 807 } 808 container advanced-compare { 809 when '../severity != "all" and 810 ../severity != "none"' { 811 description 812 "The advanced compare container is not applicable for 813 severity 'all' or severity 'none'"; 814 } 815 if-feature select-adv-compare; 816 leaf compare { 817 type enumeration { 818 enum equals { 819 description 820 "This enum specifies that the severity comparison 821 operation will be equals."; 822 } 823 enum equals-or-higher { 824 description 825 "This enum specifies that the severity comparison 826 operation will be equals or higher."; 827 } 828 } 829 default equals-or-higher; 830 description 831 "The compare can be used to specify the comparison 832 operator that should be used to compare the syslog message 833 severity with the specified severity."; 834 } 835 leaf action { 836 type enumeration { 837 enum log { 838 description 839 "This enum specifies that if the compare operation is 840 true the message will be logged."; 841 } 842 enum block { 843 description 844 "This enum specifies that if the compare operation is 845 true the message will not be logged."; 846 } 847 } 848 default log; 849 description 850 "The action can be used to specify if the message should 851 be logged or blocked based on the outcome of the compare 852 operation."; 853 } 854 description 855 "This container describes additional severity compare 856 operations that can be used in place of the default 857 severity comparison. The compare leaf specifies the type of 858 the compare that is done and the action leaf specifies the 859 intended result. 860 Example: compare->equals and action->no-match means 861 messages that have a severity that is not equal to the 862 specified severity will be logged."; 863 } 864 } 866 grouping selector { 867 description 868 "This grouping defines a syslog selector which is used to 869 select log messages for the log-actions (console, file, 870 remote, etc.). Choose one or both of the following: 871 facility [ ...] 872 pattern-match regular-expression-match-string 873 If both facility and pattern-match are specified, both must 874 match in order for a log message to be selected."; 875 container facility-filter { 876 description 877 "This container describes the syslog filter parameters."; 878 list facility-list { 879 key "facility severity"; 880 ordered-by user; 881 description 882 "This list describes a collection of syslog 883 facilities and severities."; 884 leaf facility { 885 type union { 886 type identityref { 887 base syslog-facility; 888 } 889 type enumeration { 890 enum all { 891 description 892 "This enum describes the case where all 893 facilities are requested."; 894 } 895 } 896 } 897 description 898 "The leaf uniquely identifies a syslog facility."; 899 } 900 uses severity-filter; 901 } 902 } 903 leaf pattern-match { 904 if-feature select-match; 905 type string; 906 description 907 "This leaf describes a Posix 1003.2 regular expression 908 string that can be used to select a syslog message for 909 logging. The match is performed on the SYSLOG-MSG field."; 910 reference 911 "RFC 5424: The Syslog Protocol 912 Std-1003.1-2008 Regular Expressions"; 914 } 915 } 917 grouping structured-data { 918 description 919 "This grouping defines the syslog structured data option 920 which is used to select the format used to write log 921 messages."; 922 leaf structured-data { 923 if-feature structured-data; 924 type boolean; 925 default false; 926 description 927 "This leaf describes how log messages are written. 928 If true, messages will be written with one or more 929 STRUCTURED-DATA elements; if false, messages will be 930 written with STRUCTURED-DATA = NILVALUE."; 931 reference 932 "RFC 5424: The Syslog Protocol"; 933 } 934 } 936 container syslog { 937 presence "Enables logging."; 938 description 939 "This container describes the configuration parameters for 940 syslog."; 941 container actions { 942 description 943 "This container describes the log-action parameters 944 for syslog."; 945 container console { 946 if-feature console-action; 947 presence "Enables logging to the console"; 948 description 949 "This container describes the configuration parameters 950 for console logging."; 951 uses selector; 952 } 953 container file { 954 if-feature file-action; 955 description 956 "This container describes the configuration parameters for 957 file logging. If file-archive limits are not supplied, it 958 is assumed that the local implementation defined limits 959 will be used."; 960 list log-file { 961 key "name"; 962 description 963 "This list describes a collection of local logging 964 files."; 965 leaf name { 966 type inet:uri { 967 pattern 'file:.*'; 969 } 970 description 971 "This leaf specifies the name of the log file which 972 MUST use the uri scheme file:."; 973 } 974 uses selector; 975 uses structured-data; 976 container file-rotation { 977 description 978 "This container describes the configuration 979 parameters for log file rotation."; 980 leaf number-of-files { 981 if-feature file-limit-size; 982 type uint32; 983 default 1; 984 description 985 "This leaf specifies the maximum number of log 986 files retained. Specify 1 for implementations 987 that only support one log file."; 988 } 989 leaf max-file-size { 990 if-feature file-limit-size; 991 type uint32; 992 units "megabytes"; 993 description 994 "This leaf specifies the maximum log file size."; 995 } 996 leaf rollover { 997 if-feature file-limit-duration; 998 type uint32; 999 units "minutes"; 1000 description 1001 "This leaf specifies the length of time that log 1002 events should be written to a specific log file. 1003 Log events that arrive after the rollover period 1004 cause the current log file to be closed and a new 1005 log file to be opened."; 1006 } 1007 leaf retention { 1008 if-feature file-limit-duration; 1009 type uint32; 1010 units "minutes"; 1011 description 1012 "This leaf specifies the length of time that 1013 completed/closed log event files should be stored 1014 in the file system before they are removed."; 1015 } 1016 } 1017 } 1018 } 1019 container remote { 1020 if-feature remote-action; 1021 description 1022 "This container describes the configuration parameters 1023 for forwarding syslog messages to remote relays or 1024 collectors."; 1025 list destination { 1026 key "name"; 1027 description 1028 "This list describes a collection of remote logging 1029 destinations."; 1030 leaf name { 1031 type string; 1032 description 1033 "An arbitrary name for the endpoint to connect to."; 1034 } 1035 choice transport { 1036 mandatory true; 1037 description 1038 "This choice describes the transport option."; 1039 case udp { 1040 container udp { 1041 description 1042 "This container describes the UDP transport 1043 options."; 1044 reference 1045 "RFC 5426: Transmission of Syslog Messages over 1046 UDP"; 1047 leaf address { 1048 type inet:host; 1049 description 1050 "The leaf uniquely specifies the address of 1051 the remote host. One of the following must be 1052 specified: an ipv4 address, an ipv6 address, 1053 or a host name."; 1054 } 1055 leaf port { 1056 type inet:port-number; 1057 default 514; 1058 description 1059 "This leaf specifies the port number used to 1060 deliver messages to the remote server."; 1061 } 1062 } 1063 } 1064 case tls { 1065 container tls { 1066 description 1067 "This container describes the TLS transport 1068 options."; 1069 reference 1070 "RFC 5425: Transport Layer Security (TLS) 1071 Transport Mapping for Syslog "; 1072 leaf address { 1073 type inet:host; 1074 description 1075 "The leaf uniquely specifies the address of 1076 the remote host. One of the following must be 1077 specified: an ipv4 address, an ipv6 address, 1078 or a host name."; 1079 } 1080 leaf port { 1081 type inet:port-number; 1082 default 6514; 1083 description 1084 "TCP port 6514 has been allocated as the default 1085 port for syslog over TLS."; 1086 } 1087 uses tlsc:tls-client-grouping; 1088 } 1089 } 1090 } 1091 uses selector; 1092 uses structured-data; 1093 leaf facility-override { 1094 type identityref { 1095 base syslog-facility; 1096 } 1097 description 1098 "If specified, this leaf specifies the facility used 1099 to override the facility in messages delivered to 1100 the remote server."; 1101 } 1102 leaf source-interface { 1103 if-feature remote-source-interface; 1104 type if:interface-ref; 1105 description 1106 "This leaf sets the source interface to be used to 1107 send messages to the remote syslog server. If not 1108 set, messages can be sent on any interface."; 1109 } 1110 container signing { 1111 if-feature signed-messages; 1112 presence 1113 "If present, syslog-signing options is activated."; 1114 description 1115 "This container describes the configuration 1116 parameters for signed syslog messages."; 1117 reference 1118 "RFC 5848: Signed Syslog Messages"; 1119 container cert-signers { 1120 description 1121 "This container describes the signing certificate 1122 configuration for Signature Group 0 which covers 1123 the case for administrators who want all Signature 1124 Blocks to be sent to a single destination."; 1125 list cert-signer { 1126 key "name"; 1127 description 1128 "This list describes a collection of syslog 1129 message signers."; 1130 leaf name { 1131 type string; 1132 description 1133 "This leaf specifies the name of the syslog 1134 message signer."; 1135 } 1136 container cert { 1137 uses ks:private-key-grouping; 1138 uses ks:certificate-grouping; 1139 description 1140 "This is the certificate that is periodically 1141 sent to the remote receiver. Selection of the 1142 certificate also implicitly selects the private 1143 key used to sign the syslog messages."; 1144 } 1145 leaf hash-algorithm { 1146 type enumeration { 1147 enum SHA1 { 1148 value 1; 1149 description 1150 "This enum describes the SHA1 algorithm."; 1151 } 1152 enum SHA256 { 1153 value 2; 1154 description 1155 "This enum describes the SHA256 algorithm."; 1156 } 1157 } 1158 description 1159 "This leaf describes the syslog signer hash 1160 algorithm used."; 1161 } 1162 } 1163 leaf cert-initial-repeat { 1164 type uint32; 1165 default 3; 1166 description 1167 "This leaf specifies the number of times each 1168 Certificate Block should be sent before the first 1169 message is sent."; 1170 } 1171 leaf cert-resend-delay { 1172 type uint32; 1173 units "seconds"; 1174 default 3600; 1175 description 1176 "This leaf specifies the maximum time delay in 1177 seconds until resending the Certificate Block."; 1178 } 1179 leaf cert-resend-count { 1180 type uint32; 1181 default 0; 1182 description 1183 "This leaf specifies the maximum number of other 1184 syslog messages to send until resending the 1185 Certificate Block."; 1186 } 1187 leaf sig-max-delay { 1188 type uint32; 1189 units "seconds"; 1190 default 60; 1191 description 1192 "This leaf specifies when to generate a new 1193 Signature Block. If this many seconds have 1194 elapsed since the message with the first message 1195 number of the Signature Block was sent, a new 1196 Signature Block should be generated."; 1197 } 1198 leaf sig-number-resends { 1199 type uint32; 1200 default 0; 1201 description 1202 "This leaf specifies the number of times a 1203 Signature Block is resent. (It is recommended to 1204 select a value of greater than 0 in particular 1205 when the UDP transport RFC 5426 is used.)."; 1206 } 1207 leaf sig-resend-delay { 1208 type uint32; 1209 units "seconds"; 1210 default 5; 1211 description 1212 "This leaf specifies when to send the next 1213 Signature Block transmission based on time. If 1214 this many seconds have elapsed since the previous 1215 sending of this Signature Block, resend it."; 1216 } 1217 leaf sig-resend-count { 1218 type uint32; 1219 default 0; 1220 description 1221 "This leaf specifies when to send the next 1222 Signature Block transmission based on a count. 1223 If this many other syslog messages have been 1224 sent since the previous sending of this 1225 Signature Block, resend it. A value of 0 means 1226 that you don't resend based on the number of 1227 messages."; 1228 } 1229 } 1230 } 1231 } 1232 } 1233 } 1234 } 1235 } 1236 1238 Figure 3. ietf-syslog Module 1240 5. Usage Examples 1242 Requirement: 1243 Enable console logging of syslogs of severity critical 1245 1246 1247 1248 1249 1250 all 1251 critical 1252 1253 1254 1255 1256 1258 Enable remote logging of syslogs to udp destination 1259 foo.example.com for facility auth, severity error 1261 1262 1263 1264 1265 remote1 1266 1267
foo.example.com
1268 1269 1270 1271 auth 1272 error 1273 1274 1275 1276 1277 1278 1280 Figure 4. ietf-syslog Examples 1282 6. Acknowledgements 1284 The authors wish to thank the following who commented on this 1285 proposal: 1287 Andy Bierman, Martin Bjorklund, Alex Campbell, Alex Clemm, Francis 1288 Dupont, Jim Gibson, Jeffrey Haas, Bob Harold, John Heasley, Giles 1289 Heron, Lisa Huang, Mahesh Jethanandani, Warren Kumari, Jeffrey K 1290 Lange, Jan Lindblad, Chris Lonvick, Alexey Melnikov, Kathleen 1291 Moriarty, Tom Petch, Juergen Schoenwaelder, Phil Shafer, Yaron 1292 Sheffer, Jason Sterne, Peter Van Horne, Kent Watsen, Bert Wijnen, 1293 Dale R Worley, and Aleksandr Zhdankin. 1295 7. IANA Considerations 1297 7.1. The IETF XML Registry 1299 This document registers one URI in the IETF XML registry [RFC3688]. 1300 Following the format in [RFC3688], the following registration is 1301 requested: 1303 URI: urn:ietf:params:xml:ns:yang:ietf-syslog 1304 Registrant Contact: The IESG. 1305 XML: N/A, the requested URI is an XML namespace. 1307 7.2. The YANG Module Names Registry 1309 This document registers one YANG module in the YANG Module Names 1310 registry [RFC7895]. Following the format in [RFC7950], the following 1311 registration is requested: 1313 name: ietf-syslog 1314 namespace: urn:ietf:params:xml:ns:yang:ietf-syslog 1315 prefix: ietf-syslog 1316 reference: RFC zzzz 1318 8. Security Considerations 1320 The YANG module defined in this document is designed to be accessed 1321 via YANG based management protocols, such as NETCONF [RFC6241] and 1322 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1323 implement secure transport layers (e.g., SSH, TLS) with mutual 1324 authentication. 1326 The NETCONF access control model (NACM) [RFC6536] provides the means 1327 to restrict access for particular users to a pre-configured subset of 1328 all available protocol operations and content. 1330 There are a number of data nodes defined in this YANG module that are 1331 writable/creatable/deletable (i.e., config true, which is the 1332 default). These data nodes should be considered sensitive or 1333 vulnerable in all network environments. Logging in particular is 1334 used to assess the state of systems and can be used to indicate a 1335 network compromise. If logging were to be disabled through malicious 1336 means, attacks may not be readily detectable. Therefore write 1337 operations (e.g., edit-config) to these data nodes without proper 1338 protection can have a negative effect on network operations and on 1339 network security. 1341 In addition there are data nodes that require careful analysis and 1342 review. These are the subtrees and data nodes and their sensitivity/ 1343 vulnerability: 1345 facility-filter/pattern-match: When writing this node, 1346 implementations MUST ensure that the regular expression pattern 1347 match is not constructed to cause a regular expression denial 1348 of service attack due to a pattern that causes the regular 1349 expression implementation to work very slowly (exponentially 1350 related to input size). 1352 remote/destination/signing/cert-signer: When writing this subtree, 1353 implementations MUST NOT specify a private key that is used for 1354 any other purpose. 1356 Some of the readable data nodes in this YANG module may be considered 1357 sensitive or vulnerable in some network environments. It is thus 1358 important to control read access (e.g., via get, get-config, or 1359 notification) to these data nodes. These are the subtrees and data 1360 nodes and their sensitivity/vulnerability: 1362 remote/destination/transport: This subtree contains information 1363 about other hosts in the network, and the TLS transport 1364 certificate properties if TLS is selected as the transport 1365 protocol. 1367 remote/destination/signing: This subtree contains information 1368 about the syslog message signing properties including signing 1369 certificate information. 1371 There are no RPC operations defined in this YANG module. 1373 9. References 1375 9.1. Normative References 1377 [I-D.ietf-netconf-keystore] 1378 Watsen, K., "YANG Data Model for a "Keystore" Mechanism", 1379 Internet-Draft draft-ietf-netconf-keystore-04, October 1380 2017. 1382 [I-D.ietf-netconf-tls-client-server] 1383 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 1384 TLS Servers", Internet-Draft draft-ietf-netconf-tls- 1385 client-server-05, October 2017. 1387 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1388 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1389 RFC2119, March 1997, . 1392 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, DOI 1393 10.17487/RFC5424, March 2009, . 1396 [RFC5425] Miao, F., Ed., Ma, Y.Ed., and J. Salowey, Ed., "Transport 1397 Layer Security (TLS) Transport Mapping for Syslog", RFC 1398 5425, DOI 10.17487/RFC5425, March 2009, . 1401 [RFC5426] Okmianski, A., "Transmission of Syslog Messages over UDP", 1402 RFC 5426, DOI 10.17487/RFC5426, March 2009, . 1405 [RFC5848] Kelsey, J., Callas, J. and A. Clemm, "Signed Syslog 1406 Messages", RFC 5848, DOI 10.17487/RFC5848, May 2010, 1407 . 1409 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1410 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1411 . 1413 [RFC7895] Bierman, A., Bjorklund, M. and K. Watsen, "YANG Module 1414 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1415 . 1417 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1418 RFC 7950, DOI 10.17487/RFC7950, August 2016, . 1421 [RFC8089] Kerwin, M., "The "file" URI Scheme", RFC 8089, DOI 1422 10.17487/RFC8089, February 2017, . 1425 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1426 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1427 May 2017, . 1429 [Std-1003.1-2008] 1430 The Open Group, ""Chapter 9: Regular Expressions". The 1431 Open Group Base Specifications Issue 6, IEEE Std 1432 1003.1-2008, 2016 Edition.", September 2016, . 1435 9.2. Informative References 1437 [I-D.ietf-netmod-revised-datastores] 1438 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K. 1439 and R. Wilton, "Network Management Datastore 1440 Architecture", Internet-Draft draft-ietf-netmod-revised- 1441 datastores-10, January 2018. 1443 [I-D.ietf-netmod-yang-tree-diagrams] 1444 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 1445 Internet-Draft draft-ietf-netmod-yang-tree-diagrams-06, 1446 February 2018. 1448 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1449 DOI 10.17487/RFC3688, January 2004, . 1452 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J.Ed., 1453 and A. Bierman, Ed., "Network Configuration Protocol 1454 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1455 . 1457 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1458 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 1459 10.17487/RFC6536, March 2012, . 1462 [RFC8040] Bierman, A., Bjorklund, M. and K. Watsen, "RESTCONF 1463 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1464 . 1466 Appendix A. Implementor Guidelines 1468 Appendix A.1. Extending Facilities 1470 Many vendors extend the list of facilities available for logging in 1471 their implementation. Additional facilities may not work with the 1472 syslog protocol as defined in [RFC5424] and hence such facilities 1473 apply for local syslog-like logging functionality. 1475 The following is an example that shows how additional facilities 1476 could be added to the list of available facilities (in this example 1477 two facilities are added): 1479 module example-vendor-syslog-types { 1480 namespace "http://example.com/ns/vendor-syslog-types"; 1481 prefix vendor-syslogtypes; 1483 import ietf-syslog { 1484 prefix syslogtypes; 1485 } 1487 organization "Example, Inc."; 1488 contact 1489 "Example, Inc. 1490 Customer Service 1492 E-mail: syslog-yang@example.com"; 1494 description 1495 "This module contains a collection of vendor-specific YANG type 1496 definitions for SYSLOG."; 1498 revision 2017-08-11 { 1499 description 1500 "Version 1.0"; 1501 reference 1502 "Vendor SYSLOG Types: SYSLOG YANG Model"; 1503 } 1505 identity vendor_specific_type_1 { 1506 base syslogtypes:syslog-facility; 1507 description 1508 "Adding vendor specific type 1 to syslog-facility"; 1509 } 1511 identity vendor_specific_type_2 { 1512 base syslogtypes:syslog-facility; 1513 description 1514 "Adding vendor specific type 2 to syslog-facility"; 1515 } 1516 } 1518 Authors' Addresses 1520 Clyde Wildes, editor 1521 Cisco Systems Inc. 1522 170 West Tasman Drive 1523 San Jose, CA 95134 1524 US 1526 Phone: +1 408 527-2672 1527 Email: cwildes@cisco.com 1528 Kiran Koushik, editor 1529 Verizon Wireless 1530 500 W Dove Rd. 1531 Southlake, TX 76092 1532 US 1534 Phone: +1 512 650-0210 1535 Email: kirankoushik.agraharasreenivasa@verizonwireless.com