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.

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.

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.

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:

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
            }

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.

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.

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
 server will be down soon, but he has still a chance to complete its request.

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".

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":

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

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:

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.

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.

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.

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.

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.

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.

7. Bibliography

[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.

8. Authors' Addresses

Alex Karasulu
Apache Software Foundation
akarasulu@apache.org

Emmanuel Lecharney
Apache Software Foundation
elecharny@apache.org

9. State diagrams

9.1. Graceful Shutdown diagram

9.2. Graceful Disconnect diagram