Dashboard > ApacheDS Addons > ... > Developer's Guide > LDAP Extensions for Graceful Shutdown > Information > Page Comparison
Log In   View a printable version of the current page.
ApacheDS Addons
LDAP Extensions for Graceful Shutdown
Version 23 by Emmanuel Lécharny
on Jan 21, 2006 09:35.

<< Changes from 22 to 23
compared with
Current by Alex Karasulu
on Jan 21, 2006 17:45.
(show comment)
 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 3 changes. View first change.

 {warning}
 This is a draft of a draft: draft-ietf-ldapext-shutdown-01. It might be submitted or it might not. All I know is I will implement it for ApacheDS so clients can properly handle offlined replicas for service windows without downtime.
 {warning}
  
 h1. 1. Status of this Memo
 This document is an Internet-Draft and is in full conformance with all
 provisions of Section 10 of RFC2026. Internet-Drafts are working docu\-
 ments of the Internet Engineering Task Force (IETF), its areas, and its
 working groups. Note that other groups may also distribute working
 documents as Internet-Drafts.
  
 Internet-Drafts are draft documents valid for a maximum of six months
 and may be updated, replaced, or obsoleted by other documents at any
 time. It is inappropriate to use Internet-Drafts as reference material
 or to cite them other than as "work in progress."
  
 The list of current Internet-Drafts can be accessed at
 [http://www.ietf.org/ietf/1id-abstracts.txt].
  
 The list of Internet-Draft Shadow Directories can be accessed at
 [http://www.ietf.org/shadow.html].
  
 This draft document will be submitted to the RFC Editor as an Informa\-
 tional document. Distribution of this memo is unlimited. Technical dis\-
 cussion of this document will take place on the Apache Directory Project
 mailing list <dev@directory.apache.org>. Please send editorial comments
 directly to the editor <akarasulu@apache.org>.
  
 Copyright (C) The Internet Society (2006). All Rights Reserved.
  
 Please see the Copyright section near the end of this document for more
 information.
  
 h1. 2. Abstract
 This document defines two extended LDAPv3 [LDAP] messages to gracefully
 manage server's that must go offline or shutdown with proper notifica\-
 tion to bound clients. A DSA may be put offline, or shutdown for up\-
 grades or scheduled maintenance during designated service windows.
 Replicas may be taken offline during non-overlapping service windows to
 make sure the service is available to clients thereby minimizing downtime.
 Clients should be able to handle DSA downtime by switching to replicas
 and blacklisting the offlined server. Once the DSA comes back online,
 after the end of a service window, the client can remove the DSA from
 the blacklist to participate in balancing requests across replicas.
  
 h1. 3. GracefulShutdown ExtendedRequest
 This ExtendedRequest message may be sent to offline or shutdown a DSA
 supporting this extension. Regardless of whether the service process ends
 or not, it stops accepting connections at the host address and port this
 message was sent to immediately upon receipt. The requestName is set to
 the OBJECT IDENTIFIER "1.2.6.1.4.1.18060.1.1.1.100.3". The requestValue
 is represented by the ASN.1 structure below:
 {noformat}
 GracefulShutdown ::= SEQUENCE {
  timeOffline INTEGER (0..720) DEFAULT 0, -- Maximum time off line is one day
  delay [1] INTEGER (0..86400) DEFAULT 0 -- Maximum delay is one day
  }
 {noformat}
 After unbinding from the service port, the server MUST begin notifying
 clients using unsolicited notification. If the value for timeOffline is
 set to zero, the server MUST send a Notice of Disconnect and close the
 TCP connection to the client. Otherwise the server MUST first send a
 GracefulDisconnect ExtendedResponse described in section 4 below followed
 by a Notice of Disconnect after which the TCP connection with the client
 MUST be closed. The client supporting the GracefulDisconnect extension
 MAY terminate the connection before a Notice of Disconnect can be
 delivered. After notifying all clients and closing their connections,
 the DSA process MAY terminate.
  
 h2. 3.1 Time Offline in Minutes
 The expected time, in minutes, the server is to be offline is advertized
 using the timeOffline field. The value should be interpretted as the minimum
 time the server will be offline. The server MAY infact be offline for
 longer than this expected time in minutes. By default it is 0, and this
 value is interpretted as, the time offline is undetermined.
  
 The server uses this value to inform clients of the, service window using
 the GracefulDisconnect ExtendedResponse as an unsolicited notification.
  
 h2. 3.2 Delay in Seconds
 The delay, in seconds, before the server will stop accepting new connections.Its default value is 0, which
 means that the server will immediatly stop accepting requests. This can be used to inform the user that the
 &nbsp;server will be down soon, but he has still a chance to complete its request.
  
 h2. 3.3 Security Considerations
 Obviously, only superusers should be authorized to shutdown a shared server.
 The GracefulShutdown ExtendedRequest will issue a response with a resultCode
 of SUCCESS if the user has permissions to shutdown the server. If the user
 is not authorized to shutdown the server, the server MUST return a response
 with a resultCode of insufficientAccessRights(50) instead. The responseName
 MUST always be set to the OBJECT IDENTIFIER "1.2.6.1.4.1.18060.1.1.1.100.4".
  
 h1. 4 GracefulDisconnect ExtendedResponse
 The Notice of Disconnect alone is not enough for some clients to react prop\-
 erly to planned service windows. The client can only poll to see if the ser\-
 vice comes back online at some time. If informed of the amount of time the
 service is expected to be offline, the client may check back later, after
 the specified service window has elapsed, to see if the server is back
 online. This is much better than polling or indefinately blacklisting the
 replica as failed forever. To utilize this information, clients must be
 aware of the GracefulDisconnect unsolicited notification with the
 responseName set to the OBJECT IDENTIFIER "1.2.6.1.4.1.18060.1.1.1.100.5":
 {noformat}
 GracefulDisconnect ::= SEQUENCE {
  timeOffline INTEGER (0..720) DEFAULT 0,
  delay [0] INTEGER (0..86400) DEFAULT 0,
  replicatedContexts Referral OPTIONAL
  }
  
 Referral ::= SEQUENCE OF LDAPURL
  
 LDAPURL ::= LDAPString -- limited to characters permitted in URLs
  
 LDAPString ::= OCTET STRING
 {noformat}
 When the timeOffline value defaults to zero, the GracefulDisconnect
 effectively resembles a Notice of Disconnect with a slight difference: the
 client MAY presume the disconnect was due to an emergency as opposed to a
 planned outage.
  
 It is very unlikely to obtain a delay value 0, because the server will then be unavailable.
 Any other value gives the number of second before the server will be unreachable.
  
 If the server is a replica within one or more clusters, it MAY optionally
 recommend alternative replicas for specific naming contexts using a SEQUENCE
 of LDAPURL in the replicatedContexts field. The LDAPURLs contained shall not
 contain any search attributes or search scope specifiers. These URLs only
 contain the scheme, host, port, and optionally a DN. The DN may be specified
 in case replicas only replicate specific contexts and not the entire DIT. If
 no DN is specified in the LDAPURL every namingContext of the offlined server
 is replicated in the replica.
  
 As an example presume 5 server's exist: A, B, C, D, and E. The following
 namingContexts are served by these servers:
 || Server || namingContexts ||
 | A | dc=example,dc=com |
 | B | dc=example,dc=com |
 | C | dc=example,dc=com |
 | C | dc=apache,dc=org |
 | D | dc=apache,dc=org |
 | E | dc=example,dc=com |
 | E | dc=apache,dc=org |
 If server A is shutting down gracefully it MAY offer the following
 alternative replicatedContexts as LDAPURLs to clients being disconnected
 gracefully:
  
 ldap://A
 ldap://B
 ldap://C
  
 If server D is shutting down gracefully it MAY offer include the following
 LDAPURLs:
  
 ldap://C
  
 Now the interesting case is when server C (or E) is shut down gracefully.
 The GracefulDisconnect notifications they send out will contain the
 following LDAPURLs:
  
 ldap://A/dc=example,dc=com
 ldap://B/dc=example,dc=com
 ldap://D/dc=apache,dc=org
 ldap://E
  
 Clients MAY disregard the DN component of the LDAPURL however then they would
 need to read the RootDSE to determine the same information.
  
 h1. 5. Intended Use
 Some of the scenarios that the Graceful Shutdown mechanism described in
 this document is designed to support are described in this section.
 Other uses of the mechanism are possible as well.
  
 h2. 5.1. Graceful, Standard and in Band Mechanism for Shuting Down Servers
 All directory servers can just as easily be shutdown using OS signals. The
 "gracefulness" of some platforms for handling these events can be debated
 ad infinitum. Timing issues may result and sometimes the results are
 nondeterministic. This mechanism offers the server a chance to respond
 properly, notifying all clients before going offline.
  
 h2. 5.2. Reduced Polling to Determine Availability
 Clients need not permenantly blacklist servers taken offline for scheduled
 maintenance. Nor do they need to poll for their availability to remove them
 from blacklists. Clients can gracefully deal with offlined replicas without
 excessive network communication, or loss of redundancy for prolonged periods
 of time.
  
 Different strategies can be taken based on the notifications recieved. For
 example servers which simply go offline without notification can be
 blacklisted for a long time: checked perhaps daily for availability. Those
 server which provide the standard notice of disconnect notification, then go
 offline may be polled with geometricly increasing periods with some upper
 limit. For example the server might be check in the following intervals, one
 minute, two minutes, four minutes, eight minutes, and so on until an upper
 limit of an hour is exceeded.
  
 If the server notified clients with a GracefulDisconnect that has a non-zero
 timeOffline value, then those client can queue the server for reinstatement
 using a timer. If the server does not come back online then the previous
 polling strategy may be taken.
  
 Most servers that go offline do so for scheduled maintenance more frequently then
 they do for catastrophic reasons or for impromtu maintenance.
  
 h2. 5.3. Simpler Clients without Interruption
 Clients may have a simpler design and use less resources if they do not have to
 poll for the availability of a service. Furthermore there is less of an
 interruption with clear alternatives using LDAPURLs if replication is enabled.
  
 h1. 6. Copyright
 Copyright (C) The Internet Society (2006). All Rights Reserved.
  
 This document and translations of it may be copied and furnished to oth\-
 ers, and derivative works that comment on or otherwise explain it or
 assist in its implementation may be prepared, copied, published and dis\-
 tributed, in whole or in part, without restriction of any kind, provided
 that the above copyright notice and this paragraph are included on all
 such copies and derivative works. However, this document itself may not
 be modified in any way, such as by removing the copyright notice or
 references to the Internet Society or other Internet organizations,
 except as needed for the purpose of developing Internet standards in
 which case the procedures for copyrights defined in the Internet Stan\-
 dards process must be followed, or as required to translate it into
 languages other than English.
  
 The limited permissions granted above are perpetual and will not be
 revoked by the Internet Society or its successors or assigns.
  
 This document and the information contained herein is provided on an "AS
 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT\-
 NESS FOR A PARTICULAR PURPOSE.
  
 h1. 7. Bibliography
 {noformat}
 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
  ment Levels", RFC 2119, March 1997.
  
 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
  Protocol (v3)", RFC 2251, December 1997.
 {noformat}
  
 h1. 8. Authors' Addresses
 Alex Karasulu
  Apache Software Foundation
  akarasulu@apache.org
  
 h1. State diagrams
  Emmanuel Lecharney
  Apache Software Foundation
  elecharny@apache.org
  
h2. Graceful Shutdown diagram
  h1. 9. State diagrams
  
 h2. 9.1. Graceful Shutdown diagram
 !GracefulShutdown.png!
  
 h2. Graceful Disconnect diagram
  h2. 9.2. Graceful Disconnect diagram
 !GracefulDisconnect.png!
Site running on a free Atlassian Confluence Open Source Project License granted to Safehaus. Evaluate Confluence today.
Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.5.4 Build:#809 Jun 12, 2007) - Bug/feature request - Contact Administrators