[Linux-ha-dev] firstest, earliest draft of STONITH-2 API...

[Alan Robertson]

Hi,

Attached you'll find my first thoughts about the STONITH 2 API.

As you can see, I've made it a little more "normal", and a little less 
AlanPeculiar.  (It still will have plugins, they'll be a little less 
obvious than before).

And, you'll notice I don't define anything about the XML DTD or anything 
similar...  But, it should be parallel to the OCF DTD as far as parameters, 
etc.

For, now let's just look at the functions, parameters, etc. and see what I 
mangled, left out, or otherwise botched...

Then, after I'm bloodied and bruised, and we fix it up the way everyone 
wants it to be, we someone who knows what they're doing can go at the DTD ;-).



-- 
     Alan Robertson <alanr at unix.sh>

"Openness is the foundation and preservative of friendship...  Let me claim 
from you at all times your undisguised opinions." - William Wilberforce
-------------- next part --------------
/* $Id: stonith.h,v 1.10 2004/10/07 11:22:27 lars Exp $ */
/*
 *	S hoot
 *	T he
 *	O ther
 *	N ode
 *	I n
 *	T he
 *	H ead
 *
 *	Cause the other machine to reboot or die - now.
 *
 *	We guarantee that when we report that the machine has been
 *	rebooted, then it has been (barring misconfiguration or hardware
 *	errors)
 *
 *	A machine which we have STONITHed won't do anything more to its
 *	peripherials etc. until it goes through the reboot cycle.
 */

/*
 *
 * Copyright (c) 2000 Alan Robertson <alanr at unix.sh>
 * Copyright (c) 2004 International Business Machines, Inc.
 *
 * Author: Alan Robertson
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */

#ifndef __STONITH_H
#	define __STONITH_H

#define	STONITH_VERS	2

/*
 *	Return codes from "Stonith" operations
 */

#define	S_OK		0	/* Machine correctly reset	*/
#define	S_BADCONFIG	1	/* Bad config info given	*/
#define	S_ACCESS	2	/* Can't access STONITH device	*/
				/* (login/passwd problem?)	*/
#define	S_INVAL		3	/* Bad/illegal argument		*/
#define	S_BADHOST	4	/* Bad/illegal host/node name	*/
#define	S_RESETFAIL	5	/* Reset failed			*/
#define	S_TIMEOUT	6	/* Timed out in the dialogues	*/
#define	S_ISOFF		7	/* Can't reboot: Outlet is off	*/
#define	S_OOPS		8	/* Something strange happened	*/

typedef struct stonith {
	char *		stype;
	void *		pinfo;
}Stonith;

/* An array of StonithNVpairs is terminated by a NULL s_name */
typedef struct {
	char *	s_name;
	char *	s_value;
}StonithNVpair;

/*
 *	Operation requested by reset_req()
 */
#define	ST_GENERIC_RESET	1 /* Reset the machine any way you can */
#define	ST_POWERON		2 /* Power the node on */
#define	ST_POWEROFF		3 /* Power the node off */
/*
 *	Type of information requested by the getinfo() call
 */
#define ST_CONF_XML	1	/* XML config info */
#define ST_DEVICEID	2	/* Device Type Identification */
#define ST_DEVICENAME	3	/* Unique Individual Device Identification */
				/* (only after stonith_set_config() call) */
#define ST_DEVICEDESCR	4	/* Device Description text */
#define ST_DEVICEURL	5	/* Manufacturer/Device URL */

char **	stonith_types(void);	/* NULL-terminated list */
				/* valid until next call of stonith_types() */
Stonith*stonith_new(const char * type);
void	stonith_delete(Stonith *);

int	stonith_get_confignames	(Stonith* s, const char** s_names);
				/* static/global return */
				/* Return number and list of valid s_names */
char*	stonith_getinfo		(Stonith* s, StonithInfo infotype);
				/* static/global return - lots of things! */
int	stonith_set_config	(Stonith* s, StonithNVpair* list);
	/*
	 * Must call stonith_set_config() before calling functions below...
	 */
char**	stonith_get_hostlist	(Stonith* s);
void	stonith_free_hostlist	(Stonith* s, char** hostlist);
int	stonith_get_status	(Stonith* s, const char * node);
int	stonith_reset_req	(Stonith* s, StonithOp operation
				,	const char* node);
/*
 * The ST_DEVICEID info call is intended to return the type of the Stonith
 * device.  Note that it may return a different result once it has attempted
 * to talk to the device (like after a status() call).  This is because
 * a given STONITH module may be able to talk to more than one kind of
 * model of STONITH device, and can't tell which type is out there
 * to until it talks to it.  For example, Baytech 3, Baytech 5 and
 * Baytech 5a are all supported by one module, and this module actually
 * captures the particular model number after it talks to it.
 *
 * The ST_DEVICEDESCR info call is intended to return information identifying
 * the type of STONITH device supported by this STONITH object.  This is so
 * users can tell if they have this kind of device or not.
 *
 * SHOULD THIS BE IN THE XML SO IT CAN BE SUPPLIED IN SEVERAL LANGUAGES??
 * But, this would mean the STONITH command would have to parse XML.
 * Sigh...  I'd rather not...  Or maybe it can be supplied duplicately
 * in the XML if that is thought to be desirable...
 *
 * The ST_DEVICEURL info call is intended to return the URL of a web site
 * related to the device in question.  This might be the manufacturer,
 * a pointer to the product line, or the individual product itself.
 *
 * A good way for a GUI to work which configures STONITH devices would be to
 * use the result of the stonith_types() call in a pulldown menu.
 *
 * Once the type is selected, create a Stonith object of the selected type.
 * One can then create a dialog box to create the configuration info for the
 * device using return from the ST_CONF_XML info call to direct the
 * GUI in what information to ask for to fill up the StonithNVpair
 * argument to the stonith_set_config() call.  This information would then
 * be prompted for according to the XML information, and then put into
 * a NULL-terminated array of StonithNVpair objects.
 *
 * Once this has been done, it can be tested for syntactic
 * validity with stonith_set_config().
 *
 * If it passes set_config(), it can be further validated using status()
 * which will then actually try and talk to the STONITH device.  If status()
 * returns S_OK, then communication with the device was successfully
 * established.
 *
 * Normally that would mean that logins, passwords, device names, and IP
 * addresses, etc. have been validated as required by the particular device.
 *
 * At this point, you can ask the device which machines it knows how to reset
 * using the stonith_get_hostlist() function.
 *
 */

#endif /*__STONITH_H*/