ts4-faq.txt

				TS4 FAQ
				=======

---------------------------------------------------------------------------

*) What is the status of TS4's development?
*) What is the political status of TS4's features?
*) Where do I find detailed technical information?
*) What are the major new features of TS4?
*) What arbitrary limits are involved?
*) What was that about +channels?
*) How do I use channel passwords?
*) What can opers do about channels?
*) What if I don't want passwords on my channel?  How do I check?
*) Any more channel password quirks that we should know of?
*) How do I pick my channel password?
*) Won't people try to crack my channel password?
*) How do half-ops work?
*) Can half-ops give +h to other users?
*) How do I send a message to the ops (or halfops, or voices) on a channel?
*) ircII says something about "DCC TALK"!
*) How do exceptions work?
*) Do these new modes work consistently in a mixed network?
*) How does nick collision recovery work?
*) How does op recovery work?
*) How do I run my channel with TS4?
*) I'm a client coder; what should my client do to support TS4?
*) TS4 killed my cat, what do I do?

---------------------------------------------------------------------------


*) What is the political status of TS4's features on EFnet?

	There isn't going to be a massive switch-over to the TS4 code on
	EFnet.  The main reason is that there is no agreement among the
	admins about deploying mode +c, and that the rest is not 
	considered important enough to do a mass upgrade for.

	So, instead, the best parts of the TS4 code are going to be
	integrated in the next versions of the 'mainline' EFnet server
	code.

	This FAQ describes the TS4 code as it is, in its entirety.  So
	not all of it will apply to EFnet.  Anything related to channel
	passwords and clearing channels most likely won't.


*) What is the status of TS4's development?

	Beta testing is over; it was hard at the start, with lots of
	bugs and crashes, but it seems to have been running very
	smoothly for weeks now, so I call it stable.


*) Where do I find detailed technical information?

	FAQ:	http://www.eleves.ens.fr:8080/home/espel/ircd/TS4.FAQ

	Protocol specs for TS4: 
		http://www.eleves.ens.fr:8080/home/espel/ircd/README.TS4

	General EFnet ircd and TS4 information: 
		http://www.eleves.ens.fr:8080/home/espel/ircd/


*) What are the major new features of TS4?

	User features:

		1. channel mode +c, which lets operators globally
		   preserve ops on a channel, protected with a
		   password.

		2. mode +h for users on all channels; this gives "half-ops".

		3. channel mode +e, which keeps a list of patterns that
		   can join even if they match a ban.

		4. nick collision recovery: after a nick collision or
		   any other kind of server kill, the user is prompted
		   for a new nickname, instead of resetting the
		   connection.

		5. short-term op recovery: lets you have ops on a
		   channel if you had them when you disconnected a few
		   minutes ago.  authentification is done via a 'cookie'
		   generated by the server.

		6. added a way to send messages to the ops on a channel
		   (or the ops and halfops, or the ops, halfops and
		   voices).

		7. bans and exceptions are now timestamped.  after a
		   split, any bans on the newer side will be removed,
		   and the older side won't ever see them.  just like it
		   already was with the rest of the channel modes.

		8. opers now have a way to clear a channel completely, at
		   at the discretion of their admin.

	Server features, transparent to the user:

		1. connection ID's are used instead of nicknames, in
		   communication between servers, to refer to users.
		   this eliminates desynchs and problems like messages
		   going to the wrong user because of nick changes.

		2. automatic removal of dependent clients; this saves
		   bandwith during splits.

		3. traffic between servers is now (optionally)
		   compressed; this saves a lot of bandwith, at the
		   expense of some CPU.

		4. some changes in how servers negotiate versions;
		   compatibility with non-TS or pre-TS3 servers is gone.


*) What arbitrary limits are involved?

	These are still negotiable; if you think any of them should be
	increased or lowered, feel free to yell about it.

	.  Servers won't take channel mode +c for channels created
	   before a set date (not yet specified).  This is because +c
	   on a mixed net would be confusing, and also to leave it to
	   channels to decide if and when they want to switch to +c.

	.  A channel needs to have existed for 48 hours to be able to
	   get a channel password with mode +c.

	.  Mode +c will automatically be removed from any channel that
	   has been opless and halfop-less or empty for approximately
	   48 hours.

	.  Exceptions and bans are counted together; at most 20 of them
	   can be set on a channel, for a total length of 1024 bytes.

	.  Short-term op recovery will ignore any channel that has been
	   created less than an hour before.  It will keep at most
	   10 channels for one user, and for at most 15 minutes.

	.  Channel passwords can only be queried for approximately 15
	   minutes after they have been set.  After that time, the server
	   forgets the actual password, and keeps only a hashed version
	   from which the password cannot be derived (for extra security).


*) What was that about +channels?

	At some point we were planning to introduce a new hiearchy
	of channels, +channels, and make MODE +c work only there.

	This has been abandoned as too confusing.  Instead, channels
	that want to "opt out" of +c can be created at any time
	with "/join #channel none".


*) How do I use channel passwords?

	On a #channel that is at least 48 hours old, any chanop can set a
	channel password with the command "/mode #channel +c password".
	Most printable characters are allowed in passwords; spaces aren't.
	If there is already a password, the new overrides the old.  It is
	not allowed to mix "mode +c" with other mode changes on the same
	line.

	When someone sets a channel password, all clients on the channel
	see something like "*** Mode change "+c" on channel #channel".
	The actual password is not shown.

	To query the channel password, you need to do "/mode #channel c",
	and you'll get the password in a numeric reply, or an error message.

	To remove a channel password, you do "/mode #channel -c".  No
	argument is needed (if you supply one, it will be ignored).

	Servers purposefully forget the actual passwords after a while
	(15 minutes or a little more), keeping only a hashed version
	that can be used to verify a password, but from which the actual
	password cannot be calculated.  Any attempt to query the
	actual password after it has been forgotten returns an error
	numeric.  Note that this doesn't remove any power from the
	chanops, as they can still remove the password with "/mode -c".

	Anyone, whether on the channel or not, and with ops or not, can
	check if a channel password is valid, with the command 
	"/mode #channel =c password", and get a numeric reply.  This is
	different from +c and -c in that it never sets, changes or
	removes the current password.

	If you put the right channel password on a "join" command, after
	the channel name, you will enter the channel regardless of any
	other modes (+i, +k, bans, etc), and you will be given ops.  The
	channel (including yourself) will see you opped by your server.

	A channel that has a password will be kept around even if it
	becomes empty; joining such an empty channel without the
	password won't give you ops.  After 48 hours of being empty or
	opless, the server will issue a "mode -c" and remove the
	password.

	Opers can NOT see or reset channel passwords for users.


*) What can opers do about channels?

	Once the whole network has switched to TS4 (and NOT BEFORE!),
	there is a framework in place to allow entire channels to be reset
	(cleared).  This removes all users, modes, keys and passwords
	from a channel; there is no way to just remove a key or just
	bring ops back.

	It is not yet defined who will be able to clear channels, and
	under which conditions.

	Whatever opers have the possibility of doing, it still won't be
	OK in most cases to go whine at an oper if your channel has been
	taken, for the very simple reason that the oper has absolutely
	NO REASON to believe you.


*) How does clearing channels work?  (for opers where this is allowed)

	You use "/clearchan #channel reason", or
	"/quote clearchan #channel :reason" if your client doesn't
	support /clearchan as a command, which is quite likely.

	The channel has to exist to be clearable; you also need to be
	opered, /clearchan must be activated at your server, and it must
	be activated on your O:line.  An O:line that allows /clearchan
	has an "8" in the field before the class, as in

		O:<host>:<pass>:<nick>:8:<class>

	Most importantly, the WHOLE NETWORK needs to be TS4 for /clearchan
	to work, and it should only be used when you REALLY REALLY know
	what you are doing and why.

	Clearing a channel kicks everyone and sets mode +z on the channel;
	then only opers can join and get ops.  They can then join, take
	mode +z off, maybe set +s or +i or both, invite whoever needs
	to join and give ops to whoever should have them.

	The fact that a channel is cleared propagates on a netjoin,
	but weird things can happen if a channel gets cleared on both
	sides of a split.


*) What if I don't want passwords on my channel?  How do I check?

	To make a channel that cannot have a channel password, create
	it with "/join #channel none" instead of just "/join #channel".

	To check if you _can_ have a password on your channel, type
	"/mode #channel" and watch the reply with the creation time.
	It should consist of 3 numbers.  The first of them is the
	channel's TS; the second is the channel's password TS, and the
	third is the time since the channel is opless, if it is.

	If the channel can NOT get a +c password without being recreated
	(either because its TS is to old, or because it was created with
	that option), the two last numbers will be "-1".

	If your client doesn't show that well, you can also try setting
	"/mode #channel +c whatever", even without being an op.  If your
	channel cannot have +c, the server will tell you "+c is an
	unknown mode char to me".


*) Any more channel password quirks that we should know of?

	If you set the password to the special value "none", it will
	never be considered to be matched (so a "/join #channel none"
	will never give you ops).  A channel with a password of "none"
	will still remain for 48 hours when it becomes empty.

	Clear passwords are not passed after splits when servers connect
	to each other, so you cannot query the current password after
	a server has set it.

	Don't forget that "/mode #channel =c password" lets you check if
	a password is valid, without requiring ops, and that an op can
	remove the current password without knowing it.

	Empty channels are not passed on server reconnection either,
	since they are supposed to be kept by both sides already.  This
	means that a server that is restarted will not know of any empty
	passworded channels.  If you re-create the channel on such a
	server, you will get ops, but you won't be able to see or
	override the password which is kept on other servers.  If,
	afterwards, someone joins on another server, using the password,
	their ops will be associated with an older TS than yours, and
	you will be automatically deopped.  This is normal, expected
	behavior; it's not supposed to happen often.


*) How do I pick my channel password?

	The basic, obvious rule is that a channel password should be
	very hard to guess.  
	
	Do not use a dictionary word (in any language) as a password, or
	one or two words, even with their spellings changed, or with
	mixed caps, or with letters replaced by symbols.

	Make use of the fact that passwords can be quite long (up to 23
	characters).  The easiest way to make a fairly good password is
	to pick three (two are not enough) completely unrelated words,
	separated by dashes or any other symbol.  Examples of this would
	be "folky-step-perish" or "pocket_dial_tick".  For inspiration,
	open a dictionary at random pages.

	Another popular way to make good passwords is to pick a long
	phrase and then keep the first letter of each word.  For
	example, you you could set the password to "iwntratpr" and
	remember "I will not turn right after the phone rings".  Avoid
	popular quotes, just make something up.

	And of course, the best way to generate passwords is to have a
	program generate them randomly for you.  These passwords will be
	a pain to remember, but that won't be a problem if your IRC
	client or script can remember them for you.


*) Won't people try to crack my channel password?

	They can try, but if your password is reasonably good, they
	don't have a chance at all.

	To try a brute-force attack on a channel password, a bot needs
	to be sending commands like "mode #channel =c something" as fast
	as the server will take them, which is one every 2 seconds.

	Compare this to cracking Unix passwords off an /etc/passwd file,
	where no network traffic is involved, and the bruteforce program
	can try thousands of passwords every second.  If your password
	can be cracked, it means it was so weak to begin with that you
	only have yourself to blame.  A 7-letter random password would
	take over 250 years to find by brute-force, trying one every 2
	seconds.  And you can go up to 23 letters.

	This is also the reason why the command "mode #channel =c pass"
	is usable even from outside of the channel:  pointless as this
	may be, eventually someone will try to crack a channel password
	with a bruteforce bot.  A bot sending a "mode =c" command every
	two seconds uses next to nothing of the server's CPU, and
	generates no global network traffic.  On the other hand, if this
	command wasn't available, a bot trying to crack a channel with
	repeated JOINs and PARTs would be flooding the whole network
	with them.


*) How do half-ops work?

	If you're a chanop, you can make someone a halfop with the
	command "/mode #channel +h his_nick".  This cannot be mixed with
	mode changes of other types (like +v, +i, etc) on the same line.
	Up to four +/-h mode changes can be given in one "mode" command.

	A half-op can set the following modes: +b, +e, +i, +k, +l, +m,
	+n, +s, +t, +v, +h  (in other words, everything but +o, +c and
	+p).

	A half-op can change the topic even if the channel is +t, speak
	even if the channel is +m, invite people even if the channel is
	invite-only, and kick anyone who isn't a chanop.

	Mode +h isn't accepted on zero-TS channels.  Re-create your
	channels if you want to use this.

	On /who and /whois replies, half-ops will have a '%' next to
	their nick, just like ops have a '@'.  On /names replies, and on
	the name lists that show up automatically when you join a channel,
	half-ops will either have a '%' or a '+' (the latter being for
	compatibility with clients that don't expect a '%' there and use
	that line to build the channel's userlist).


*) How do I send a message to the ops (or halfops, or voices) on a channel?

	A message sent to @#channel goes only to the chanops on the
	#channel.

	A message sent to @%#channel goes to the chanops and halfops of
	the channel.

	A message sent to @+#channel goes to the chanops, halfops and
	voices of the channel.

	If the channel has mode +n set, then only chanops can send
	messages to @#channel; only chanops and halfops can send to
	@%#channel, and only chanops, halfops and voices can send to
	@+#channel.   
	
	If mode +n isn't set, then anyone can send to all these targets,
	from inside or outside of the channel.


*) ircII says something about "DCC TALK"!

	Most versions of ircII give a special meaning to message targets
	starting with a '@', related to communicating with 'talk' clients.

	The suggested fix is to define these three aliases in your
	".ircrc" or some other /load'ed file:

	/^alias wall  quote privmsg @$C :$*
	/^alias wallh quote privmsg @%$C :$*
	/^alias wallv quote privmsg @+$C :$*

	And then use the commands /wall, /wallh and /wallv to send
	message to chanops, chanops and halfops, and chanops halfops and
	voices, respectively.

	All these commands act on the current channel.


*) Can half-ops give +h to other users?

	Yes, and they can take it away too, unless the channel has mode
	+p set.  In that case, only ops can give or take away +h. 

	Half-ops cannot set nor remove mode +p.  Until all servers are
	TS4, half-ops cannot set mode +s when +p is set, because that
	would clear mode +p.


*) How do exceptions work?

	Just like bans, except that the mode is +e rather than +b.
	Exceptions always take precedence over bans.

	For example, to ban everyone from aol.com except for
	yourfriend@some.host.aol.com, you'd do:

		/mode #channel +b *!*@*.aol.com
		/mode #channel +e *!*yourfriend@some.host.aol.com

	You can't group mode +e with other modes on the same line, nor
	use exceptions on zero-TS channels.


*) Do these new modes work consistently in a mixed network?

	Kind of.  
	
	New modes won't propagate across older servers, so your
	exceptions will only be active on part of the net.  Giving
	half-op status to people won't have any effect if there are
	non-TS4 servers between you and them.  

	Half-ops who are not ops will be seen as plain non-ops from
	older servers, so depending on the exact version of ircd on
	those older servers, they may ignore any mode changes from the
	half-op.  They will still recognize kicks.

	Channel passwords would not behave very well on a mixed net,
	so they will only be available for channels created after a
	certain date (unspecified as of now), when hopefully all servers
	will have switched to TS4.


*) How does nick collision recovery work?

	Instead of getting disconnected by a nick collision or similar
	technical problem, you will get the message:

		"Nickname collision; please enter a new nick"

	At this point, no client commands will work, except for the
	command to set a new nick.  
	
	The server will make you automatically leave all your channels.
	People on other servers will see you be killed off IRC with the
	usual nick collision message.

	Once you give a new nickname, you can re-join your channels.

	This combines with the short-term op recovery system: you can
	rejoin a channel you were operator on, within 10 minutes of a
	recovered nick collision, and you will be given ops by your
	server.  


*) How does op recovery work?

	When you sign on IRC, you will be given a randomly generated
	magic cookie by your server, with a message like:
	
		"*** 8mE3jmImxdb3 :is your reconnection cookie"
	
	When you later disconnect from IRC, the server will remember the
	list of channels you were operator on (if any), associated with
	the cookie.

	If you sign on again within 10 minutes, you can identify yourself
	by giving the server the cookie from the previous connection,
	with the command "/quote cookie 8mE3jmImxdb3" (with the actual
	cookie rather than the example).   This will only work on the
	_same server_ you were connected to.

	Then, when you first join one of the channels you had ops on,
	your server will give you ops again.  Nothing special is needed
	on the "/join" line (unless the channel is +k).  Ordinary mode
	checks apply here, so this won't get you through a ban, UNLESS
	the channel has been re-created in between, in which case your
	joining deops everyone else.

	You can only identify yourself with a given cookie _once_.  The
	command "/quote cookie <something>" associates the saved list of
	channels and TS's with your connection, and forgets the cookie
	itself.  If you disconnect at that point, the list of channels
	will be saved with your new cookie from this connection, along
	with any channels you may have joined and become an operator on,
	in between.

	Ops on channels are not saved if the channel has existed for
	less than one hour at the moment you disconnect, or if the
	channel has no TS.  All saved ops expire after 10 minutes.
	Halfops are not saved.

	Note that you must send your "/quote cookie" command BEFORE
	rejoining your channels.  If your client auto-rejoins them
	before giving you a chance, try turning auto-rejoin off.


*) How do I run my channel with TS4?

	First, you need to decide if you ever want to have a password
	on your channel.  Having one means that your channel cannot be
	taken from you (as a group) unless someone gives it away.

	If you do want a channel password, then you should re-create your
	channel if it was created before the introduction date for +c
	(if it's the case, any attempt to set MODE +c will fail with
	"unknown mode character").

	If you do NOT want a password on the channel, just make sure
	that every time someone needs to re-create it, they use
	"/join #channel none" instead of just "/join #channel".  MODE +c
	will not be available on a channel created that way.

	(If you don't want a password but don't want the channel to die
	out when it empties, set an actual +c password of "none".
	Note that it's very easy to lose ops this way.)

	If you do want a password, it's a good idea to cut down the
	number of people who will have it: only those who are completely
	trusted should remain as ops, and the people who are now given
	ops from time to time should get half-ops instead.  Then decide
	on a password (among ops, that's where sending messages to
	@#channel can help), set it, don't forget it, and change it
	every so often (say, once a week).

	On a channel with a password, having more than one bot is
	completely useless.  If you do have a bot and it has ops, be
	_very_ careful who you give access to.  A _very large_ number of
	channel takeovers are currently done by hacking or getting
	access into a channel's bot.  It may well be safer not to have
	one at all.

	Make sure that everyone who has the password and uses it when 
	they join has it automated in some way that they don't have to
	type "/join #chan pass" every time, since that would probably
	end up mistyped at some point and shown in public on some other
	channel.


*) I'm a client coder; what should my client do to support TS4?

	TS4's new features have been designed to avoid confusing older
	clients whenever possible.  ircII, EPIC and sirc all mostly work
	with TS4 without modifications [someone needs to check the
	Windows and Mac clients; I can't.]

	Still, there are a number of ways a client (or script) can
	explicitly support TS4, to make things easier for the user.

	1) The very basics, that every client should do:

	.  When parsing mode changes, it's good to know that +h and +e
	   take an argument.  Clearing channels sets mode +z temporarily
	   (as in "zapped channel"), so the client shoulnd't crash on
	   seeing a mode +z or -z either.

	.  When parsing NAMES, WHOIS and WHO replies, it's good to know
	   that '%' is a user flag, and that more than one flag can
	   appear at a time (so you can have things like "@%+nick").

	.  The "End of Exception List" numeric shouldn't be displayed
	   by default.

	.  Expect to get PRIVMSGs for @#channel, @%#channel and
	   @+#channel, and show them in the same area as the channel's
	   messages (but marked in some way).  Same with @&channel,
	   @%&channel and @+&channel for local channels.

	.  Do NOT ever automatically deop people opped by servers.  This
	   is the best and easiest way to end up with an opless channel,
	   and it defeats the whole purpose of channel passwords and op
	   recovery.

	.  If your client kicks people from banned addresses, make sure
	   it also checks against exception lists (mode +e).

	.  Expect 3 parameters rather than 1 from numeric 329
	   (RPL_CREATIONTIME);  see also the list of changed and added
	   numerics on README.TS4.

	2) Possible additions:

	.  If the client has ban management functions, the same
	   functions should be offered to manage exception lists.

	.  There should be a command or button to join a channel using a
	   password, prompting the user for the password without
	   displaying it on the screen.  
	   
	.  Even better, a list of known passwords could be saved to a
	   file (readable only by the user); the client would then use
	   the saved password (if there's one), instead of prompting.
	   The user should have a way to add, remove and change elements
	   in the list, from within the client.

	.  Whenever the client sees a "mode +c" on a channel, it could
	   query the server for the password, and remember it.  It
	   should _not_ show it on the screen by default (you don't want
	   passwords shown automatically when there could be someone
	   looking behind the user's shoulder).

	.  Expect to get PART commands for yourself from the server, 
	   even if the user has not requested to leave any channels (this
	   happens with recovered nick collisions).  For GUI clients,
	   you might want to leave the client a chance to read the
	   channel window contents.

	.  When you get the "nick lost" numeric (453), prompt the user
	   for a new nick, and send an ordinary nick change command to
	   the server.	Any commands sent in between can get ignored with
	   "not registered" errors from the server.

	.  Clients should be able to handle reconnection cookies
	   automatically: whenever you connect to a server and get back
	   a cookie (with the numeric 014, "<cookie> :is your
	   reconnection cookie"), the client should store the cookie,
	   along with the server name and the current time, in a file.
	   At that same moment, the client should look if there is a
	   previously saved cookie for that server; if there is one,
	   delete it from the file, and send it to the server, unless it
	   is more than 10 minutes old.

	   (This is close to how webserver cookies work, which is why
	   these are also called cookies.  There are no privacy concerns
	   associated with IRC cookies, unlike their web counterpart).


*) TS4 killed my cat, what do I do?

	If you think you found a bug, mail me at
	<espel@llaic.u-clermont1.fr> with a detailed description of what
	happened.

	Make sure to mention what servers were involved, what version of
	ircd they were running ("/version server.name" to find out),
	what channels were involved, and the full TS information for
	these channels ("/mode channelname" to find out; make sure to
	get the 3 numbers in the numeric reply (329) that comes after
	the channel modes).

	Behavior that can't be reproduced is very hard to trace; if you
	find a way to reliably reproduce your bug, you're likely to get
	an explanation or a fix very quickly.