citadel/docs/room-sharing-howto.txt

   1  Room Sharing in Citadel/UX
   2  --------------------------
   3
   4  One way to "keep the conversation going" on your Citadel system is to share
   5 rooms with other Citadel systems.  This process has been streamlined in recent
   6 versions and is now very easy.  In a shared room, a message posted to the room
   7 is automatically propagated to every system on the network.  It's kind of like
   8 a UseNet newsgroup, but without the spam.
   9
  10  Obviously, the first thing you have to do is find another Citadel to share
  11 rooms with, and make arrangements with them.  The following Citadels are a good
  12 place to start:
  13
  14  The Dog Pound II   dogpound2.citadel.org
  15  UNCENSORED!        uncensored.citadel.org
  16  PixelBBS           pixel.citadel.org
  17
  18  You don't have to be a part of the citadel.org domain to participate in the
  19 Citadel network, but the DNS service is provided free of charge by the Citadel
  20 community if you wish to do this.
  21
  22  Before we get into the technical nitty gritty, there are two points of
  23 etiquette to keep in mind.  The first thing to keep in mind is that the
  24 operator of any particular Citadel may not be willing to share some of his/her
  25 rooms.  Some sites are proud to offer exclusive content in certain areas.
  26 Chances are, if a room is already being shared on the network, it's available
  27 for anyone to share; if not, it can't hurt to ask -- but take care not to
  28 demand it of them.  Ask if you may share the room instead of telling them that
  29 you wish to share the room.  When looking at a <K>nown rooms list, network
  30 rooms are the ones ending in parentheses instead of angle brackets.  For
  31 example, "Gateway)" would be a network room, "Lobby>" would not.
  32
  33  The other point of etiquette to remember is that you should be making the
  34 arrangements in advance, and then set it up.  It is extremely rude to simply
  35 begin networking with another Citadel without first obtaining permission from
  36 its operator.  Always ask first.  Most Citadel operators are more than happy
  37 to network with you.  Also, if later on you decide to take your system down,
  38 please take the time to notify the operators of any other Citadels you network
  39 with, so they can unconfigure their end.
  40
  41
  42  Ok, first things first.  On a Citadel room sharing network, the first thing
  43 you need to know is your own system's node name.  Presumably you set this
  44 up during installation, but if you want to change it you can do so using the
  45 <.A>ide <S>ysconfig <G>eneral command:
  46
  47 Lobby> . Aide System configuration General
  48 Node name [uncnsrd]:
  49 Fully qualified domain name [uncensored.citadel.org]:
  50 Human readable node name [Uncensored]:
  51
  52  The "node name" is important, it's how the network identifies messages
  53 coming from your system.  The "human readable node name" is simply a label;
  54 it shows up in messages coming from your system.  "Fully qualified domain
  55 name" is your DNS name; it's used for routing messages on the Internet.  In
  56 the above example, the node name is "uncnsrd".
  57
  58
  59  The next thing you need to do is configure your neighbor node(s).  You need
  60 to do this for each node you network with.  Let's say you wanted to talk to
  61 a Citadel system called "frobozz".  Use the <.A>ide <S>ysconfig <N>etwork
  62 command:
  63
  64 Lobby> . Aide System configuration Network
  65 ###    Node            Secret                   Host or IP             Port#
  66 --- ---------------- ---------------- -------------------------------- -----
  67 <A>dd <D>elete <S>ave <Q>uit  -> Add
  68
  69 Enter node name    : frobozz
  70 Enter shared secret: frotz
  71 Enter host or IP   : frobozz.magick.org
  72 Enter port number  :  [504]: 504
  73
  74 ###    Node            Secret                   Host or IP             Port#
  75 --- ---------------- ---------------- -------------------------------- -----
  76   1 frobozz          frotz            frobozz.magick.org               504
  77 <A>dd <D>elete <S>ave <Q>uit  -> Save
  78
  79 Lobby>
  80
  81  As you can see in the above example, you have to enter the Citadel node name,
  82 the DNS name or IP address of the server, and the port number the Citadel
  83 service is running on.  The "shared secret" is a password to allow the two
  84 Citadel nodes to connect to each other to exchange network data.  The password
  85 must be *identical* on both ends of the connection -- when the operator of
  86 the other Citadel node sets up the connection with your system, he/she must
  87 use the same password.
  88
  89
  90  Now you're ready to share rooms.  You have to do this for each room you want
  91 to share, and you have to do it from BOTH ENDS -- again, when you share a room
  92 with another Citadel, they must share it with you as well.  Let's say you have
  93 a room called "Quiche Recipes>" and you want to share it with the node you
  94 set up above.  First, edit the room and flag it as a network room:
  95
  96 Quiche Recipes> . Aide Edit this room
  97 Room name [Quiche Recipes]:
  98 Private room  [No]: No
  99 Preferred users only  [No]: No
 100 Read-only room  [No]: No
 101 Directory room  [No]: No
 102 Permanent room  [No]: No
 103 Network shared room  [No]: Yes
 104 Automatically make all messages anonymous  [No]: No
 105 Ask users whether to make messages anonymous  [No]: No
 106 Listing order [64]:
 107 Room aide (or 'none') [none]:
 108 Message expire policy (? for list) [0]:
 109 Save changes (y/n)? Yes
 110 Ok
 111
 112 Quiche Recipes)
 113
 114  Notice how the prompt changed?  It was > before, but it's ) now.  That means
 115 it's a network room.  Now you can tell Citadel that you want to share the room
 116 with frobozz.  Enter this command:
 117
 118 Quiche Recipes) . Aide Network room sharing
 119
 120  Your text editor will pop up (you *did* configure Citadel to use your
 121 favorite text editor, right?) with a screen that looks like this:
 122
 123 # Configuration for room: Quiche Recipes
 124 # Nodes with which we share this room
 125 # Specify one per line.
 126
 127  All you have to do is enter the name of the other Citadel node (i.e.
 128 "frobozz" in our example) on a line by itself.  As usual, lines starting with
 129 a "#" are comments.  Just go to the end of the file, type "frobozz" (without
 130 the quotes), save the file... and you're done!
 131
 132
 133  At this point, you just sit back and enjoy.  Your Citadel and the other one
 134 will begin polling each other at regular intervals (once per hour by default)
 135 and sharing messages.
 136
 137 If once/hour is not acceptable you can change the default of one hour
 138 polling.
 139
 140 Type .asg (.Aide System-configuration General) and find the line:
 141
 142   How often to run network jobs (in seconds) [3600]:
 143
 144 And change it to whatever you like.  For example, 15 minutes is 900
 145 seconds.  So if you changed the default value to 900, you'd poll out every
 146 15 minutes.
 147