# ysmICQ client Users' Guide

## Pointing Instant Messaging users in the right direction

###

Copyright © 2003 rad2k at mail dot ru.

## Chapter 1. Introduction to ysm

A description of the project aimed to provide enough information to visitors as well as to new ysm users.

## What is ysm?

The acronym 'ysm' stands for 'You Sick Me', an ironic name I came up with while surfing the 'I Seek You' (ICQ) protocol. YSM is a portable open source console ICQ client written in the C language, under the GPL license.

YSM is one of the new generation clients due to the sudden modifications the ICQ protocol suffered after Mirabilis joined the dark-side of the force (AOL). This is the reason why most ICQ clients ended up with malfunctions or unable to use the IM network at all.

YSM was (proudly) the first ICQ clone to download and upload server-side contact lists.

The idea behind ysm is to have a portable-quickcompiling console client which lacks of strict library dependencies. The environment around ysm is ment to be fun and comfortable.

## Available features

These are the list of available features the last release of ysm provides:

- Plaintext and AES encrypted ICQ messages sending/receiving.

- Plaintext and AES encrypted File transfers.

- Downloading and Uploading of serverside contact lists.

- Fingerprinting of remote ICQ clients.

- Sending/Receiving of URLs and contacts.

- Ignore, Visible and Invisible lists management.

- and more features.. alert, forwarding, seen, afk, etc..

## Supported Platforms

At the moment of writing this document, ysm is known to run on RISC and CISC microprocessors. Tested platforms include:

- Ms.Windows 9x/NT/2k/XP - x86

- Linux distributions - x86

- BSD (open,net,free) - x86

- QNX - x86

- Solaris - x86

- BeOS - x86

- Solaris - ultra sparc 64

- Irix64 - MIPS

If you know of any other non listed tested platform, please let me know.

## Vocabulary

The following are a list of words used in ysm which may not have an obvious meaning:

SLAVE: an ICQ contact.

AFK:

(Away from keyboard), is one of the features ysm provides. AFK may either be activated manually or triggered automatically when a specified amount of minutes with no keyboard input is reached.

When AFK is activated, the following steps are followed:

- An automatic response message is sent to whoever messages you.

- The message is logged. (readable using the 'readafk' command.)

MOOD: ICQ status [ONLINE, AWAY, DND, NA, OCCUPIED, FREECHAT, INVISIBLE]

## Chapter 2. Installing ysm

A step by step chapter that will guide you through the process of downloading and installing ysm.

## Where do I get ysm?

Sources as well as binary versions of ysm can be downloaded from the project's official sourceforge space.

For an updated list of download mirrors check ysm's website.

ysm is also available in many popular systems package Ports. check yours!

## System requirements

One of the ideas behind ysm was to preserve the code portability and to eliminate strict library dependencies. This is the principal reason for the short amount of requirements needed to compile and run ysm.

### Compiling requirements

Microsoft Windows systems: Visual c++

Other systems: cc and make

### Running requirements

None. Tested to run just great on old systems.

### Note on threads

### Warning

This note is only important for non win32 users, since MS.Windows has its own threads implementation, supported by ysm.

ysm is compatible with Posix Threads (pthreads). If your system lacks of pthread libraries ysm will build without problems but features which require threads (such as direct connections) will be disabled.

## Installing ysm from sources

### Pre-compile notes

You will first need to download the lastest version of ysm. You will find a file with a .tgz extension (tar+gz compression) or .tar.bzip extension (tar+bzip2 compression). This file includes the sources for all supported systems. Once you have downloaded the sources proceed to the following subsection.

### Pre-compile configuration

YSM provides a set of features which may be enabled or disabled before compiling. These features can be found inside the file 'YSM_Config.h' in the src/ directory.

A complete description of each feature as well as indications on how to enable/disable them is specified inside that file. I will only name the available features without a description:

- YSM_SILENT_SLAVES_STATUS

- COMPACT_DISPLAY

- YSM_MONOCHROME

- YSM_WAR_MODE

### Compiling steps

Win32 and non Win32 users will need to proceed in two different ways.

Win32 systems:

1. Use an uncompression tool (i.e: Winzip) with the downloaded sources file.

2. Double click on 'ysm.dsp' or open Visual c++ and choose File, then Open Project, browse through the uncompressed directory and double click on the 'ysm.dsp' file.

3. Press 'f7' on your keyboard to start compiling.

4. You will find the ysm binary in the Debug/ or Release/ directories of the project's directory.

Non Win32 systems:

1. Run 'gunzip filename.tgz' if the downloaded file has a .tgz extension or 'bzip2 -d filename.tar.bz2' if the downloaded file has a .tar.bz2 extension.

2. Run 'tar xvf filename.tar' to finish uncompressing the downloaded sources.

3. Enter the new directory and run './configure'.

4. Now run 'make'.

5. Optionally, as root, run 'make install' to install the binary and manpage.

### Post-compile notes

The first time you run ysm you will be prompted with the Configuration Wizard which will ask you a set of questions in order to create your configuration file.

The default name for the configuration file is 'ysm-cfg'.

The default directory where the configuration file will be stored differs on Win32 and non Win32 systems:

- In Win32 systems, the directory will be called 'ysm' and it will be created inside $USERPROFILE (nt/2k/xp/+) or C:\ (9x).

- In non Win32 systems, the directory will be called '.ysm' and it will be created inside the user's home directory.

### Note

when running ysm, you can also specify a '-c' parameter followed by a name in order to use a local configuration file named as specified. This will override the default directory and configuration file name settings, creating the configuration file in the local directory.

## Installing ysm from binaries

Please refer to the 'Post-compile notes' in the previous section for instructions.

## Chapter 3. Configuring ysm

A detailed description of the settings found in a configuration file as well as an overview of ysm client configuration related commands.

## ysm Configuration file

The slaves list and configurable settings are stored in the configuration file.

A setting can be placed anywhere between the beginning of the file and the [SLAVES] tag found at the end of the file along with your slaves.

A setting consists of a case insensitive name and a value separated by a '>' symbol (i.e.: 'NAME>VALUE'.) In several settings, a value of '1' is considered ENABLE and a value of '0' is considered DISABLE. In settings where a string is required as value, leaving the value empty will be considered DISABLE.

A slave entry (found between the [SLAVES] tag and the EOF) consists of a series of parameters separated by a ':' symbol. These parameters, in order, are: NICK:UIN:ENCRYPTIONKEY:FLAGS.

For example, an entry 'rad:63873081::' would mean a slave called rad, with an icq # 63873081, no encryption key set and no flags set.

### ICQ account settings

The following settings carry the information needed to login with your account.

UIN>

  The UIN Number is your ICQ number. This setting shouldn't be of your worry since YSM takes care of filling the parameter after asking you the first time you run YSM.

PASSWORD>

  This is the password for the previously specified ICQ number (or UIN.) Instead of specifying your plaintext password, you may leave this setting empty and YSM will prompt you for your password everytime it starts.

### ICQ server settings

The following settings carry the information needed to connect to the ICQ server.

SERVER>

  This is the address of the remote ICQ server. In case you need to use another server, just replace the default address (login.icq.com) with the one you want.

SERVERPORT>

  This is the port of the remote ICQ server. You shouldn't worry about setting this parameter. The default used is 5190.

### Default login status

This is the default status you will show up with right after logging in.

STATUS>

  The default value is ONLINE, you can select any of the following:

  - ONLINE

  - AWAY

  - NA

  - DND

  - OCCUPIED

  - FREECHAT

  - INVISIBLE

### AFK mode configuration

The following settings control the behaviour of the automatic AFK mode as well as of other AFK related commands.

IDLETIME>

  The amount of minutes to wait with no keyboard input before triggering the Automatic AFK mode. You can disable the Automatic AFK mode by specifying 0 minutes.

AFKMESSAGE>

  This will be the default message sent in the auto-reply message. The message will be used either when AFK is turned on manually and no message is specified or when the Automatic AFK mode is triggered.

AFKMAXSHOWN>

  The amount of messages shown on every page displayed by the "readafk" command. The default value is '3'.

### Proxy configuration

ysm supports HTTP and HTTPS proxy settings with or without auth negotiation.

PROXY>

  This is the IP address of the HTTP/HTTPS proxy to use. If you don't wish to use a proxy server, just specify a '0' as value.

PROXY_PORT>

  This is the port number where the proxy is listening.

PROXY_HTTPS>

  This flag tells ysm wether your proxy is an HTTPS proxy or not. If your proxy is HTTPS, set the value to '1', otherwise set it to '0'.

PROXY_AUTH>

  This flag tells ysm if your proxy requires auth negotiation. If it does, set the value to '1', otherwise set it to '0'.

PROXY_USERNAME>

  This is the username to use during an auth negotiation with your proxy.

PROXY_PASSWORD>

  This is the password to use during an auth negotiation with your proxy.

### Events Alert settings

The following settings take care of alerting the user when certain events are triggered. (Arrival of messages, alert on a user, etc.)

BEEP>

  This is the most used alert signal. You may disable beeping by specifying '0' as value. By specifying a value other than '0' you can choose the amount of times to beep when an event is triggered.

WINALERT>

  This setting is only available in win32 systems. You may select from 3 available alerting modes, the default is mode 3 :

  1. Popup the console window

  2. Blink the tray bar

  3. Popup and Blink

### Events Action settings

The following settings take care of executing commands or shellscripts when:

- a message is received
- a message is sent
- a slave goes online
- a slave goes offline
- you logoff

Besides whatever arguments you specify, ysm will call the given command/shellscript adding useful information. The result would be: [your_line] $remote_uin $remote_nick $msg_length $msg_data

EXEC_INCOMING>

  A command or shellscript to be executed on the arrival of a message.

EXEC_OUTGOING>

  A command or shellscript to be executed after a message is sent.

EXEC_ONCOMING>

  A command or shellscript to be executed when a slave goes online.

EXEC_OFFGOING>

  A command or shellscript to be executed when a slave goes offline.

EXEC_LOGOFF>

  A command or shellscript to be executed when you issue a quit command.

### Events Sound settings

The following settings take care of configuring ysm's sound support.

ysm has support for 'soundpacks'. These soundpacks are downloadable from ysm's website and include a set of wave audio files to be played when the previously described 'Event Actions' are triggered.

SOUNDS>

  Enable or disable sounds globally. To enable use '1' and to disable '0'.

SOUNDS_PROGRAM>

  Only for non win32 users. Specify a path to a program that will handle the playing of the wave files. I.e. : /usr/bin/play

SOUND_INCOMING>

  Enable (1) or disable (0) the playing of the incoming message sound.

SOUND_OUTGOING>

  Enable (1) or disable (0) the playing of the outgoing message sound.

SOUND_ONCOMING>

  Enable (1) or disable (0) the playing of the oncoming slave sound.

SOUND_OFFGOING>

  Enable (1) or disable (0) the playing of the offgoing slave sound.

SOUND_LOGOFF>

  Enable (1) or disable (0) the playing of the logging off sound.

### Executing commands from a file

ysm allows the user to specify a file from where to run commands, making possible a layer of remote account administration.

COMMANDSFILE>

  The path to a file from where ysm will run commands every 15 seconds. The lines inside will get executed one after the other without pause and behaving the same way as if they were user input. After all lines were executed, the file will be cleared.

### Charset convertion

ysm makes possible charset convertion under both win32 and non win32 systems. libiconv is used for non-win32 systems and the win32 api provides enough support.

Win32 users have a list of supported charsets in the registry under the following key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\NIs\CodePage

Non win32 users can issue an 'iconv -l' command.

CHARSET_TRANS>

  This is the charset name to use for transfering and receiving of messages.

CHARSET_LOCAL>

  This is the charset name to use for inputting and displaying messages.

### Browser configuration

You may configure a browser to be triggered from inside ysm when browsing websites (i.e.: using the 'burl' command).

BROWSER>

  This is the full path to the browser that will handle urls.

### Verbosity configuration

ysm lets you change the verbosity output level for debugging purposes.

VERBOSE>

  The default verbosity level is '5'. You can select a lower number to REMOVE output and a higher number to ADD output. Here is a list of available levels:

  - Remote status changes -> 0

  - Remote connecting information -> 1

  + Add direct connections information -> 20

  + Add data checking information -> 21

  + Add incoming/outgoing packets dump -> 22

  + Add slaves downloading processing -> 23

### Up-to-date check configuration

ysm allows an up-to-date check everytime you start it. It just compares your current version with the lastest release version, it never downloads anything.

VERSION_CHECK>

  You may specify '0' as value to disable version checking on startup.

### Global logging configuration

By enabling global logging, all normal messages from/to any slave will be logged. Global logging is enabled by default since its the base of the well known message history (readable using the 'hist' command.)

LOGALL>

  You may specify '0' as value to disable global logging.

### Messages displaying modes

ysm supports different ways of displaying new incoming messages.

MSG_KIND>

  The default mode is '2'. The list of available modes is:

  [0] - Oneline mode

  [1] - Verbose mode

  [2] - IRC style mode

### Antisocial SPAM protection mode

The antisocial mode makes possible the blocking of unexpected messages from users who aren't in our slaves list. It only blocks messages and allows the receiving of authorization requests. This way you get protected against the well known SPAM messages and you can still communicate with users outside your list.

ANTISOCIAL>

  You can enable the antisocial mode by specifying '1' as value and disable it by using '0' as value.

### Direct connection settings

ysm by default has direct connections enabled. DC allows you to establish peer to peer connections and to send/receive plain-text/encrypted file transfers.

DC_DISABLE>

  You can disable Direct connections by specifying '1' as value. Direct connections are enabled by default. By disabling direct connections you hide your internal ip address and the client doesn't bind the DC port.

DC_LAN>

  This setting makes ysm speed up DC negotiations inside a LAN (Local Area Network) by making ysm try the internal ip address first, and once connect fails, the external. You can enable it by specifying '1' as value or disable it with '0'. DC_LAN is disabled by default.

DC_PORT1>

  By specifying a value, you can force ysm to bind to a specific port in order to listen for incoming DC negotiations. This is useful for allowing file transfers in machines behind a firewall or for redirecting incoming handshakes behind NAT. Leave it empty for a random port.

DC_PORT2>

  By specifying a value, you can force ysm to bind to a specific port in order to initiate File Transfers. This is useful for allowing file transfers in machines behind a firewall or for redirecting incoming handshakes behind NAT. Leave it empty for a random port.

### Semi-automatic update of slave nicknames

This mode allows an update of your slave nicknames with their current ones. The update isn't global nor automatic. It will take effect when running the 'whois' command against a slave. If their current nick differs with the one shown in the whois information, it will automatically be updated.

UPDATENICKS>

  You can enable this mode by specifying '1' as value and disable it by using '0' as value. This mode is enabled by default.

### Win32 popup Hotkey configuration

This mode allows unminimizing a minimized ysm console window. By pressing CTRL + ALT + a key you will specify below, the minimized console window will popup from the tray bar and get active. This is a solution I came up with when I got tired of cycling through my windows with ALT + TAB. I hope you find it as much useful as I have!.

WINHOTKEY>

  You can specify a key to use with CTRL + ALT + key in order to popup the ysm console window. The default key is 's'.

## ysm Configuration commands

An overview of ysm client configuration related commands.

### Reloading the configuration file in runtime

By using this command, the user can load in ysm any modifications he made to the configuration file without having to restart the client.

loadconfig

  This command doesn't require any parameters.

### Changing Automatic AFK mode settings in runtime

By using this command, the user can turn the Automatic AFK mode ON or OFF and set the amount of minutes to wait before triggering the Automatic AFK mode. Note, the changes made using this command are temporary and won't be saved in the configuration file. For making permanent changes please refer to the section about the configuration file.

afkset [on|off]

  By specifying 'on', the Automatic AFK mode will be enabled. 'off' will disable it.

afkset [minutes]]

  This way the user may specify the amount of minutes before triggering the Automatic AFK mode.

### BEEP settings in runtime

This command can enable or disable Beeping. Note, the changes made using this command are temporary and not saved in the configuration file.

beep [on|off]

  By specifying 'on', Beeping will be enabled. 'off' will disable it.

### SOUND settings in runtime

This command can globally enable or disable sounds. Note, the changes made using this command are temporary and not saved in the configuration file.

sounds [on|off]

  By specifying 'on', sounds will be enabled. 'off' will disable them.

### Logging settings in runtime

This command can enable or disable logging on a specific slave as well as enable or disable global logging.

log [on|off]

  By specifying 'on', global logging will be enabled. 'off' will disable it.

log [slavename]

  By specifying a slavename, logging will be enabled or disabled on the specified slave, depending on its current setting.

## Chapter 4. About this guide

A few comments I have on this guide. Might be useful to someone.

I wrote this guide during a recovery period (about 48 hours) after an insignificant surgery I had.

## About DocBook

As some people might have noticed, I made use of an XML DTD called DocBook in order to organize the contents of this guide.

I recommend DocBook since it's intended to be a solution for technical documentation and, even though setting the environment to write DocBook can be a little boring, it's a quickly learnable markup language.

For those of you who are interested in writing DocBook, here are a couple of links:

setting the DocBook environment in win32 and a small DocBook introduction

Using the DocBook XSL Stylesheets

Frequently used DocBook tags

XML DTD validation

I used a win32 environment and had to replace the XT proc. with XSLTPROC.