Command Line Tools
Run the vines command at the command line to get the list of tools.
$ vines
Usage: vines [options] start|stop|restart|init|bcrypt|cert|ldap|schema
Daemon options:
-d, --daemonize Run daemonized in the background
-l, --log FILE File to redirect output (default: log/vines.log)
-P, --pid FILE File to store PID (default: pid/vines.pid)
Common options:
-h, --help Show this message
-v, --version Show version
init
The init command is a quick way to get a chat server instance configured and running.
$ vines init wonderland.lit Created example user alice@wonderland.lit with password secr3t Created example user arthur@wonderland.lit with password secr3t Initialized server directory: wonderland.lit Run 'cd wonderland.lit && vines start' to begin
This creates a directory for the wonderland.lit domain. Chat users on this server will have ID's that end with @wonderland.lit. A self-signed SSL certificate is installed in wonderland.lit/conf/certs that's used to encrypt chat connections.
The name of the directory is actually arbitrary. It doesn't need to match the domain of the chat ID's being hosted.
Linux Errors
If the hostname isn't properly configured in /etc/hosts, we might run into this error.
$ vines init wonderland.lit Created example user alice@wonderland.lit with password secr3t Created example user arthur@wonderland.lit with password secr3t getaddrinfo: Name or service not known
Luckily, the fix is simple. The localhost line in /etc/hosts needs to be configured properly by adding the machine's hostname before the localhost entries.
$ hostname fedora.wonderland.lit $ sudo vi /etc/hosts 127.0.0.1 fedora.wonderland.lit localhost.localdomain localhost $ rm -rf wonderland.lit $ vines init wonderland.lit
bcrypt
The storage engines supported out of the box all use bcrypt to securely store user passwords. When we're adding users to the database, we can use this command to generate secure passwords.
$ vines bcrypt secr3t $2a$10$JCuI3u7AAkT0jxsQHb8NWuXIhXrCGQba.n9dtZ/tojMs2x/hTkSYa
The hashed output can be copied and pasted into a database field.
$ vines bcrypt secr3t $2a$10$87oEgw75sz1YqTdlndC9tusEkhKLQg1UmSw64N8ZS0mJxrGdLucQC
Running bcrypt on the same password multiple times gives different results. This is normal and is an important property of the bcrypt algorithm. If two users use the same password, their bcrypt hashes won't match, making attacks on the password database much more difficult.
cert
The cert command creates a self-signed certificate that can be used to encrypt client and server connections. All connections to the chat server must be encrypted. There is no clear text, unencrypted mode.
$ vines cert wonderland.lit $ ls conf/certs/wonderland* wonderland.lit.crt wonderland.lit.key
The wonderland.lit.crt file contains the public key that can be shared with anyone. The wonderland.lit.key file contains the private key and must be kept secret. Make sure the file permissions allow only the chat server to read this file.
ldap
The ldap command is used to test the LDAP settings in conf/config.rb. Add an LDAP connector to a virtual host in the config.rb file and run this command to make sure we can connect properly. The JID prompt is an acronym for Jabber ID, which is the full chat ID of our test user.
$ vines ldap wonderland.lit JID: alice@wonderland.lit Password: LDAP connection failed: No such address or other socket error.
This message means the host or port isn't set correctly.
$ vines ldap wonderland.lit JID: alice@wonderland.lit Password: User not found with filter: (&(objectClass=person)(uid=alice@wonderland.lit))
We connected to the LDAP server, but the user ID and password weren't found. Check that the user_attr LDAP property points to an attribute that contains the full JID of the user. The mail attribute is usually a good choice because chat ID's and email addresses typically match.
If we're using the optional groupdn setting to limit the users allowed to login to the chat server, make sure Alice belongs to that group in the LDAP directory.
The search filter is displayed so we can use it in other LDAP debugging tools if needed.
$ vines ldap wonderland.lit JID: alice@wonderland.lit Password: Found user Alice with filter: (&(objectClass=person)(uid=alice@wonderland.lit))
Success! Users can now login to the chat server using their LDAP user ID and password.
schema
When using the SQL database storage engine, we need a way to connect to the database and create the tables and indexes. We'll use the schema command to test the following storage settings for the wonderland.lit virtual host.
host 'wonderland.lit' do
storage 'sql' do
adapter 'postgresql'
host 'localhost'
port 5432
database 'wonderland'
username ''
password ''
pool 5
end
end
We've told the chat server to store data in a PostgreSQL database named wonderland. Let's use the schema command to initialize the database.
$ vines schema wonderland.lit Various create table messages . . .
With the tables and indexes created, the database is ready to use by the chat server. Running this command again won't hurt anything. The schema objects will only be created if they don't exist.
Database Errors
If the database driver gems aren't installed, we will see this error.
$ vines schema wonderland.lit no such file to load -- pg
We need to install the pg gem when connecting to a PostgreSQL database. This gem provides the database driver that ActiveRecord uses to make the connection.
$ gem install pg Fetching: pg-0.11.0.gem (100%) Building native extensions. This could take a while. Successfully installed pg-0.11.0 1 gem installed
We'll see this error if the wonderland database hasn't been created yet.
$ vines schema wonderland.lit FATAL: database "wonderland" does not exist
The connection to the database server is working, but there's no database yet for the tables. We need to use the PostgreSQL createdb tool before we install the schema.
$ createdb wonderland $ vines schema wonderland.lit
start, stop, & restart
By default, vines runs in the foreground and logs messages to the console. This is nice for quickly testing configuration changes, but not for running a production chat server. Once we have the server configured correctly, we can run it as a background process with the -d or --daemonize flags.
$ vines -d start Vines has started $ vines stop Vines has been shutdown
When the server is running in the background it writes its process ID to a file in wonderland.lit/pid and its logs to wonderland.lit/log. We can customize where these files are located with the --pid and --log flags.
$ vines -d --pid /var/run/vines.pid --log /var/log/vines.log start Vines has started $ vines stop Vines is not running $ vines --pid /var/run/vines.pid stop Vines has been shutdown
Notice that we needed to tell the stop command where the pid file was located because we moved it to a custom location when we started the server. Without the --pid flag, the stop command thinks the server isn't running because it can't find the pid file in the default location.