psyced, formerly known as psycMUVE, started as the original implementation of the PSYC protocol. By now it is a multi protocol server which acts as a full-fledged node in both PSYC and XMPP protocols while also providing different gateway functions that enable users to access the PSYC and XMPP networks via other client protocols (IRC, Jabber, Telnet, ..).

psyced is probably also the only crazy piece of software to support the beauty of three different interserver protocols.

Read all about it and download it at http://www.psyced.org

Contents

Features

... and whatever I just forgot.

Architectures

Download for Unix and Win

You can get a copy of the git by issuing git clone git://git.psyced.org/git/psyced, then procede with ./install.sh for installation.

You can also browse the distribution or download a snapshot of the git from http://www.psyced.org/download – then procede with ./install.sh from there as well.

MacOSX

<lynX> Somebody submitted us as a native app for OSX. That's kinda okay, but somebody should tie up an easy to install binary package for Mac:psyced then.
http://osx.hyperjeff.net/Apps/apps.php?sub=100&f=irc%20server&w=1

Installation on MacOSX

Since the snapshot psyced-20070420, there shouldn't be any special steps required to run psyced under Mac OS X (testet on Mac OS X 10.4).

The only thing you need is the Xcode-Tools or your own building environment.

Bug Tracker

There is a bug tracking system at https://projects.tgbit.net/projects/psyced/

Documentation

  1. The psyced usage manuals in german and english are linked from Help:Contents.
  2. Commands for psyced operators
  3. http://www.psyced.org/DEVELOP provides a hitchhiker's guide to psyced software development.
  4. See also API.
  5. psyced is written in LPC.
  6. The textdb file format for psyctext.

message reception flow

msg%20flow%20in%20psyced.gif

With the new archetype.gen place generation system, the classes on the right side of the picture (all derivates of place/basic) are available only for compatibility. Places are in fact a lot more modular now than this picture suggests.

Configuration

Since no one actually uses XML editors, and psyced also runs on Windoofs we decided to try the .ini file format for configuration. Some other open source technologies do it, too. We do however use psycish variable names, so PSYC admins start getting used to our naming style...

This is the default psyced.ini as it comes with the distribution: http://www.psyced.org/dist/config/psyced.ini

About the INI file format

Information about the .ini Format obviously at Wikipedia:Ini File. The Windows API imposes a limit of 64KB on INI files. Also keys should not be case sensitive, but in our case they are. No document at all has approved or denied the use of the underscore character in names. One document said, .ini files simply may not have whitespace in their key and section names. Cloanto says, the files need to be encoded in latin1, but we use UTF-8. They also suggest to use LF as a line seperator, but I presume Windows Apps prefer CRLF.

See also (nothing is authoritative apparently):

As we're using psycish variable names, sections are just prepended to the "variable name". this means

[_foo]
_bar_snafu = kibo

just sets _foo_bar_snafu to kibo, just as

[_foo_bar]
_snafu = kibo

does, too.


Tuning

psyced custom-tailored for you. The local.h in your local configuration directory is the place to put advanced configuration options, which are not part of psyced.ini. The file is held in C/LPC header format. Your configuration options use #define statements, similar to the way we create places. However we are in the process of integrating the configuration options into the keyword naming strategy of PSYC, so we are migrating away from C's traditional uppercase #define's.

Check also SMTP#Installation for SMTP-specific tunings.

#define _flag_allow_invalid_host_certificate

Disable enforcement of all source hostnames in a TLS-encrypted circuit having to be listed in the node's certificate. psyced will revert to DNS resolution checking, which is suboptimal. This only affects multihoming servers: if a server is hosting users and places of several domains, he should provide the list of these names in the certificate using multiple dnsName fields. Any single hostname servers and especially anonymous client connections are not affected by this.

#define _flag_allow_certificate_name_common

Believe CN fields in X.509 certificates to be valid hostnames if dnsName isn't defined. Since all of PSYC should use new certificates, we don't need to support this deprecated practice used in old certificates.

#define _flag_disable_authentication_digest_MD5

Should you want to disable digest MD5 authentication in Jabber and elsewhere, you can do so. This will make the current psi client choke, as it no longer offers a plaintext login alternative.

#define _flag_disable_authentication_external_XMPP

If for some reason your XMPP hostname isn't the same as your PSYC hostname, and your certificate only reflects the PSYC hostname, use this flag to disable external authentication. It is however a better idea to get both hostnames into the certificate.

#define _flag_disable_authorization

Only used in particular gateway configurations. Authorization of users is not done by psyced itself, therefore all users are to be treated like registered ones.

#define _flag_disable_character_action

This disables the special shortcut character to issue actions. Usually ":".

#define _flag_disable_info_commands

Disable the default help message on unknown commands.

#define _flag_disable_info_session

Disable several potentially useful greeting and session termination messages at login and logout.

#define _flag_disable_inheritance_method

Disable method inheritance support. This makes psyced PSYC-incompliant.

#define _flag_disable_log_hosts

Do not store IP numbers or hostnames into files on harddisk. You can still inspect them as the users are online. The last login from message becomes slightly less useful by this.

#define _flag_disable_module_authentication

Disable decentralized PSYC authentication functionality.

#define _flag_disable_module_friendship

Disable PSYC friendship functionality.

#define _flag_disable_module_nickspace

Disable nickspace functionality.

#define _flag_disable_module_presence

Disable decentralized presence functionality.

#define _flag_disable_module_trust

Disable decentralized trust functionality.

#define _flag_disable_notice_place_examine_web

Do not generate inspected on ... coming from messages when somebody uses the web export feature. This is a temporary tuning until we have channels for this, or at least method filtering per user.

#define _flag_disable_places_arbitrary

Disable that arbitrary private places can be created just by making up their name. See also _path_archetype_place_default below which is disabled by this flag.

#define _flag_disable_place_default

Disable automatic entry into _place_default (as defined in psyced.ini) for all accesses, not just XMPP, which doesn't like autojoins at any time. Subscriptions are unaffected by this.

#define _flag_disable_place_enter_automatic

Disable all automatic entry into places at login (commonly termed autojoin). This affects all accesses and breaks the usefulness of subscriptions like newsfeeds.

#define _flag_disable_presence_directed_XMPP

Directed presence is a Jabber concept which, if turned off, disables XMPP clients not only from sending presence packets to peers directly, it also disables them from entering any chatrooms.

#define _flag_disable_prefix_person_SMTP

To avoid excessive SPAM friendliness on the SMTP port, person names need to be prefixed with a tilde. This setting disables such precaution and makes the JIDs used by Jabber compatible with e-mail. You can then address people by user@host over both technologies. This sounds nice, but is too easy to abuse.

#define _flag_disable_query_server

Disable support for Jabber-style methods to inquire various server statistics.

#define _flag_disable_registration

Disable user registration on all messaging protocols. See also REGISTER_URL and _flag_disable_unauthenticated_users.

#define _flag_disable_registration_XMPP

Disable user registration on just the XMPP protocol.

#define _flag_disable_request_version_IRC

Disable automatic version request from IRC clients. This means the server will no longer be able to provide client version information on your behalf.

#define _flag_disable_trust_localhost

localhost is usually considered trustworthy, allowed to transmit arbitrary packets, relay, remote control. If you can't trust your local host, activate this flag.

#define _flag_disable_unauthenticated_users

Don't allow unregistered users to connect. This is slightly different to _flag_disable_registration.

#define _flag_enable_location_forward_alternate

Different way to forward messages to clients. Probably buggy.

#define _flag_enable_manual_announce_IRC

For very advanced IRC users: Do not imply presence by the act of logging in or out, instead require users to manually use +here, +offline and similar commands. Bouncer style, maybe.

#define _flag_enable_manual_announce_telnet

For very advanced telnet users: Do not imply presence by the act of logging in or out, instead require users to manually use /here, /offline and similar commands.

#define _flag_enable_module_microblogging

Experimental support for microblogging integrated into user's web profiles.

#define _flag_enable_measurement_network_latency

This adds a timestamp to every private message and outputs occasional latency measurements to the console (when they take longer than a couple of seconds to echo).

#define _flag_enable_place_single

With this setting, psyced goes back to an old behaviour where users not using rich client protocols (and thus presumably rich user interfaces) automatically leave an old room when going into a new room. They can manually change this behaviour using /set multiplace on.

#define _flag_enable_unauthenticated_message_private

By default psyced does not allow newbie users - also known as unauthenticated - to send private messages to persons, as they could be of SPAM or other unwanted nature. Should you prefer a different behaviour, here's your tuning.

#define _flag_encode_uniforms_IRC

In early days the irssi client used to parse the @ character in a way that was not favorable for psyced. Now we don't even know of any client that runs into problems with the way we map uniforms into the IRC protocol. Should it happen to you, let us know tempestively. You may also want to activate this flag, then by issuing /set verbatimuniform off you can activate a hack that will replace all @'s with %'s. It's however always better to modify the client behaviour, because it's more comfortable to be able to use official unmodified uniforms in your client.

#define _flag_filter_strangers

By default psyced will allow strangers to talk to you. Should you want to change that globally for all of your users, this #define will do so. After that strangers will have to provide trustiness or request friendship. Unregistered users are filtered in any case.

#define _flag_log_flow_messages

Produce a log called FLOW_MESSAGES to debug how messages move around psyced.

#define _flag_log_sockets_IRC

For debugging purposes maintain a log of all protocol traffic concerning the IRC implementation. It will be kept in a log called RAW_IRC. This can cause massive amounts of data on a production server and should not be used because of the privacy implications.

#define _flag_log_sockets_PSYC

Same as above for the PSYC protocol.

#define _flag_log_sockets_XMPP

Same as above for the XMPP implementation.

#define _flag_optimize_protection_SMTP

By default psyced accepts emails from most SMTP implementations, yet deters very stupid SPAM robots. With this flag the SMTP compliance barrier is raised, making it harder for SPAM to get through, but at the same time legitimate applications like python's smtplib no longer make it.

#define _flag_provide_places_only

Change psyced's behaviour to only allow for places, no persons. This is generally unuseful, but in the way XMPP URIs are supported it will change the place addressing syntax from xmpp:*place@host to xmpp:place@host which obviously eliminates the possibility to address people on the same host (Implementation of this flag is currently limited to XMPP only. People are still allowed to use psyced, they simply will no longer be capable of communicating via XMPP directly).

#define _flag_report_bogus_certificates

Issue reports to the monitor room about funny or bogus certificates. Since on XMPP the majority of hosts is currently using improper or improperly signed certificates, and since we haven't made up our mind on our own encryption strategy, being picky on certificates isn't very useful. So by default only level-1 debug messages will be issued. Simply don't expect any communication with any remote server to be safe and private, currently.

#define _flag_reject_bogus_certificates

You can take it one step further and ensure you will only have TLS connections to servers which provide proper credentials properly signed by an authority your server is configured to trust. You will not have a lot of servers to talk to, when you do this, although there is activism heading in that direction.

#define _flag_trust_place_owners

By default the /owners command and _request_owners method are only available to administrators, operators or by trusted remote control. With this flag you activate a tiny little bit of IRC-like anarchy: You trust the owners you defined, or who became owners by being the first to enter a private owned room, to nominate further owners, potentially removing themselves from the list of owners or leading to room ownerships battles. Enjoy the fun!

#define _host_XMPP <hostname>

psyced does not support multihoming of domains over XMPP. This is a not recommendable hack that will use a different default node name in XMPP-S2S than over PSYC. Avoid needing this, but it may be useful in short phases of transition. This was formerly known as JABBER_HOST.

#define _limit_amount_history_place_default <amount>

Unless _flag_disable_place_default is in place, define the limit on how many history messages are allowed to be displayed when autojoining the _place_default (as defined in psyced.ini). If left undefined, a default of 5 is used. XMPP vs. subscriptions are unaffected by this.

#define _limit_amount_history_export <amount>

This defines the upper limit of history available by web export. The default being 24 messages.

#define _limit_amount_history_persistent <amount>

Upper limit of history getting sent to persistent storage. The default is 444 messages.

#define _limit_amount_log <amount>

Sets the maximum size of the /lastlog for persons while being logged in. The default is 777 messages.

#define _limit_amount_log_persistent <amount>

Sets the maximum size of the /lastlog when it is saved away to storage. That's normally a 100 messages.

#define _path_archetype_place_default <string>

This tuning makes a powerful change: it defines which blueprint class is to be used for all places which do not otherwise exist, that is - made up on the spot by a user accessing them.

Normally "net/place/default" will be used, but you may find it interesting to change that into any existing archetype.gen model, or write up your own.

For example you could use "net/place/_hso" should you want all created places to be featuring history, scratchpad and ownership.

Here's another example where I've chosen the archetype flags myself:

#include <net.h>
#echo Hello! This is my private archetype!
#define PLACE_STYLE
#include NET_PATH "place/archetype.gen"

I put it into my configuration directory as archetype.c and put

#define _path_archetype_place_default "local/archetype"

into local.h.

Notice how this one doesn't even #define ESSENTIALS, so the places will only come with a /style command, nothing else. Not even a /topic command. Not a useful example, but shows you the power of flexibility.

See also _flag_disable_places_arbitrary above for a way to disable arbitrary made up places in general.

#define _time_logon_delay_SMTP <seconds>

Amount of time the SMTP server waits before starting operation. This eliminates a percentage of dumb SPAM tools. The default is twenty seconds. When _level_debug is greater than 1 this delay is automatically deactivated for easier debugging.

#define _uniform_node <uniform>

Define what this psyced should believe its uniform to be, overriding any defaults made up by host and port settings in psyced.ini. This is useful when running a psyced node on a different port number as usual and enabling DNS SRV. You can now tell psyced to use a port-less uniform even if its internal logic would tell it otherwise. Using SRV is however not recommended, it just happens to work most of the time.

#define HTTP_URL <http-prefix>

If for some reason, like routing through proxies or when using kernel-based port forwarding, the server should advertise a different HTTP address than automatically defined by the host name of the server and the port number specified at configuration time, this define can be set in local.h

#define HTTP_URL "http://webapp.using.psyced.example.org"

The root slash will be appended, so have the URL end without "/" glyph.

#define HTTPS_URL <https-prefix>

Same as above for HTTP combined with TLS encryption. When defined, the server will prefer HTTPS_URL over HTTP_URL where privacy recommends it. If you are using HTTPS only, you don't need to provide any HTTP_URL or define a port for the plain HTTP service.

#define IRCGATE_NICK <nickname>

Define the nickname that gatebot will use to connect to IRC networks. Unfortunately a global define macro. Should be a local configuration option of each gateway, really.

#define MOTD_FILE <filename>

In a totally illogical way the net/irc module supports a traditional ircd message of the day file which illogically isn't being shown with any other access. The <filename> is relative to the root of the LPC sandbox, which is the world directory.

#define PSYC_SYNCHRONIZE

See Storage.

#define PUBLIC_PLACES

It's a list of public places (uniform or local nick plus description) that appears in the /rooms command and in the XMPP public room directory discovery requests. This setting is meant to be changed someday. But until then, here's how it works:

#define PUBLIC_PLACES \                                                 
       "RendezVous",   "Meet me in the Middle",                        \
       "CryptoChat",   "Only for people with working encryption",      \
       "LIVE",         "Moderated room for large scale event chats",   \
       "psyc://psyced.org/@welcome",  "So why am I supposed to get psyced?"

#define REGISTER_URL <http-prefix>

Provide a page URL for registration. Only works together with _flag_disable_registration.

#define RELAY

#define SYSTEM_SECRET

See Checksum.

#define WEB_CONFIGURE

As you restart psyced you (and everyone on localhost) will be able to access a web configuration tool at http://localhost:44444/net/http/configure mostly useful for creating places if you don't feel comfortable with writing them up by hand.

Caution: This feature might not be up to date.

Should you need to access the configuration tool from a remote host, using a tunneling technology like ssh is probably the safest approach. If that is not an option you need to put the IP number of your browsing client into ENABLE_HOSTS of the local/hosts.h file in your configuration directory. See below.

In case it's just a temporary dynamic IP number don't forget to remove that entry after web configuration is complete.

Host listings

In hosts.h you can specify the following lists of hosts.

#define ENABLED_HOSTS <hostlist>

As described in WEB_CONFIGURE above you can specifically enable hosts to access your server. You must provide IP numbers or abbreviations of them, like "127.0.0.", always with a trailing dot. The syntax is something like:

#define ENABLED_HOSTS "192.168.0.", "10."

#define DISABLED_HOSTS <hostlist>

This lets you block certain hosts from accessing your server. Same syntax as above. Example:

#define DISABLE_HOSTS "207.46.197.", "207.46.19."

Additionally there is also the /block command.

#define LOCAL_HOSTS <hostlist>

Virtual Hosts aren't really supported in psyced yet, but should you have some reason to make several psyc: uniforms point to the same server host, you can use this #define with a comma seperated list of hostnames. In this case we really mean names, not IP numbers. Wildcards and subdomains are not permitted. Example:

#define LOCAL_HOSTS "psyc.nytimes.com", "psyc.latimes.com"

How to figure out where psyced fails

Finding out where psyced does something wrong doesn't actually require you to understand the entire beast. It is sufficient that by means of debug output statements and appropriately set levels (see http://www.psyced.org/DEVELOP for help on that) you can narrow down where the mistake happens. Then, if it's not obvious, point us to it and we should be able to figure out what needs to be done in the grand scheme.

TODOs

Here are a few things that need to be done.. maybe you wanna look into them? This is a list of issues which shouldn't be too hard to solve, even for someone fresh at psyced and LPC.


- html code for manual pages should render better on mozilla (indenting error)
  (fixed on access.fmt - TODO on rest). dabei muss der <a name> in die zeile
  genommen werden und mit </a> abgeschlossen. automatisierbar!??
+ the old html code needs to be replaced by the kind that can be styled by css
+ find a way to generate manual from wiki?
+ generate help pages tuned to the needs of the user?
  (consider scheme, operator status and the like)

+ gateway email services (alerts etc) into mailcast places?
  run some gateways of that kind on psyced.org? or elsewhere?

- /log 9999999999 produces
        Numeric overflow: 1410065407 *= 4

- for irc whois _groups should be output using RPL_WHOISCHANNELS
  (groupsexpose)

- psyc/circuit:greet() reports all protocols w/out checking ports.h

+ _notice_invitation with a _tag could allow other entities than the
  explicitly invited one to follow suit

- optimization: psyc/parse is resolving the incoming hostname for each single
  message.. this is overkill. [[DNS]] reso is enough once per [[TCP]] link (unless
  of course the other side is presenting us a new hostname..)
        fip suggests to cache connected hosts in sAuthenticated()
        and delete them again on connection shutdown.

- /silence conversation doesn't filter /action

+ always requested by the channel inhabitants on traditional IRC:
  private gatebots for one user only - transport style...
  
- /set color #000000 kind of 'fails' since hex2int("000000") is the
  same as hex2int("red"): zero. return -1 for non-hex? pretty logical.

- history export doesn't show masquerade nicknames

+ install.sh sollte lieber mit bereits ausgepackten tars operieren
  können damit man darin tweaken kann und install nochmal anwerfen kann
  ... geht bei psyclpc, aber nicht beim psyced

WINDOWS DISTRIBUTION
? how can we compile SRV into erq.exe? do we care?
? which open source installer for win to use?
? what to do about psyconf.. include perl or re-implement psyconf for win?

Testimonials

Marenz: ich hab das gefuehl psyced ist viel mehr als es den anschein hat

See also