UNIX Installation

You will likely need to build Synchronet from source code for your Unix/Linux distribution, version, and platform architecture.

Before attempting to install/build Synchronet, insure that the prerequisites are installed.

You will to use a *nix terminal and command shell (e.g. sh/bash) to install and configure Synchronet.

It is recommended that you install Synchronet while logged-in with the user account that Synchronet will be run-as. If you install Synchronet with one user account and then later run with another (non-root) user account, you could encounter permissions errors.

Running the BBS servers/services (sbbs) as the system's root user is not recommended.

Use adduser (or “sudo adduser” if necessary) to create the run-as user account (e.g. sbbs).

$ adduser sbbs

On Linux, it's very convenient for the run-as user to have sudo access. To achieve this, as a sudo/root user:

$ sudo adduser sbbs sudo
$ groups sbbs
sbbs : sbbs sudo ...

Belonging to the sudo group will allow you to perform system administration functions while logged-in as the BBS run-as user through the use of the sudo command.

Use the su command to switch the current user to the run-as user (the “-” specifies to login as that user, e.g. setting the cwd to that user's home directory):

$ su - sbbs
Password:
$ whoami
sbbs

If you find it necessary to start the BBS servers/services as the root user, then you can have the BBS daemon (sbbs) automatically change to the Run-as User after it has bound the necessary TCP and UDP ports, by setting the User value of the [Unix] section of the ctrl/sbbs.ini file.

You must create the directory where Synchronet will live. Some common locations would be the home directory of the Run-as User (e.g. /home/sbbs/sbbs) or the system root directory (e.g. /sbbs). The information below will assume you are logged in as the user “sbbs”.

By default, Synchronet executables will look for files in the /sbbs/ctrl directory, so if you install Synchronet into a different directory you will need to either create a symbolic link in your root directory (e.g. ln -s /home/sbbs/sbbs /) or set the SBBSCTRL environment variable accordingly.

For example, to create your Synchronet directory in /sbbs, you could do the following:

1. $ sudo mkdir /sbbs ← (you would likely be prompted for your password to use “sudo”)
2. $ sudo chown sbbs:sbbs /sbbs ← (this will change directory ownership to the “sbbs” user and group)
3. $ cd /sbbs ← (puts you in the /sbbs directory as the “sbbs” user)

Alternatively, to create your Synchronet directory in your Run-as User's home directory (e.g. /home/sbbs), you could do the following:

1. $ mkdir ~/sbbs
2. $ cd ~/sbbs ← (puts you in the /home/sbbs/sbbs directory as the “sbbs” user)

The remaining steps assume that the current working directory is your Synchronet installation directory:

$ pwd
/sbbs

or:

$ pwd
/home/sbbs/sbbs

If a specific step below causes problems (e.g. displays an error message), click the highlighted text for more details including common causes of errors.

Choose a build method (using Git or Tarball)¹⁾:

Quick installation from Git (requires 100+MB of disk space):

• $ wget https://gitlab.synchro.net/main/sbbs/-/raw/master/install/GNUmakefile

To get and build the latest code:

• $ make install SYMLINK=1

On Linux, it's normal that the user's password may be prompted for near the end of the build process, as required to invoke the sudo setcap command to enable low-port-binding capability on the Synchronet sbbs executable.

If building on a Linux system as a user without sudo access, pass the NOCAP=1 option to disable this function²⁾:

• $ make install SYMLINK=1 NOCAP=1

Or, if you want to build a stable release from Git, specify a valid release tag on the make command-line (e.g. sbbs319b):

• $ make install SYMLINK=1 TAG=sbbs3xxx
• NOTE: this does not work with release tags earlier than sbbs319b, use the Tarball install method instead for those.

Notes:

• These commands will make and install a RELEASE build of the software. To make and install a DEBUG build instead, pass DEBUG=1 on the make command-lines.
• We don't support parallel builds (e.g. make -j) - so don't do that.
• On Linux systems, your user password will be prompted for to execute the sudo setcap command during install. If this is a problem, you can include NOCAP=1 on the make command-line to bypass that step.
• Mirrors of the install/GNUmakefile are available at
  • https://github.com/SynchronetBBS/sbbs/raw/master/install/GNUmakefile
  • https://gitlab.com/SynchronetBBS/sbbs/-/raw/master/install/GNUmakefile

If you installed with the SYMLINK=1 option, the resulting installation directory tree should look like this:

drwxr-xr-x 1 sbbs sbbs  2418 Jan 26 23:24 ctrl
lrwxrwxrwx 1 sbbs sbbs    25 Jan 26 21:03 docs -> /home/sbbs/sbbs/repo/docs
lrwxrwxrwx 1 sbbs sbbs    25 Jan 26 21:03 exec -> /home/sbbs/sbbs/repo/exec
-rw-r--r-- 1 sbbs sbbs 11001 Jan 26 20:51 GNUmakefile
drwxr-xr-x 1 sbbs sbbs   116 Jan 26 21:07 node1
drwxr-xr-x 1 sbbs sbbs    48 Jan 26 21:06 node2
drwxr-xr-x 1 sbbs sbbs    48 Jan 26 21:06 node3
drwxr-xr-x 1 sbbs sbbs    48 Jan 26 21:06 node4
drwxr-xr-x 1 sbbs sbbs   240 Jan 26 20:58 repo
lrwxrwxrwx 1 sbbs sbbs    25 Jan 26 21:03 text -> /home/sbbs/sbbs/repo/text
lrwxrwxrwx 1 sbbs sbbs    24 Jan 26 21:03 web -> /home/sbbs/sbbs/repo/web
lrwxrwxrwx 1 sbbs sbbs    26 Jan 26 21:03 webv4 -> /home/sbbs/sbbs/repo/webv4
lrwxrwxrwx 1 sbbs sbbs    25 Jan 26 21:03 xtrn -> /home/sbbs/sbbs/repo/xtrn

Due to the symbolic directory links (represented with -> arrows above), subsequent git pull operations (in the sbbs/repo directory) will automatically update the docs, exec, text, web, webv4, and xtrn directories. This means that any local changes (configurations or customizations) of files in those directories may need to be merged with any upstream changes later. Most configuration files are located in the ctrl directory so they are automatically excluded from any update/merge issues.

Notes:

• You can safely remove the installation GNUmakefile once successfully installed; it has served its purpose.

Alternatively, if you don't have a working Git client or are low on available disk space, you can use the following steps to install the latest nightly development build:

1. $ wget ftp://vert.synchro.net/Synchronet/sbbs_src.tgz
2. $ wget ftp://vert.synchro.net/Synchronet/sbbs_run.tgz
3. $ tar -xzf sbbs_src.tgz
4. $ tar -xzf sbbs_run.tgz
5. $ echo RELEASE=1 > src/build/localdefs.mk
6. $ cd src/sbbs3
7. $ SBBSEXEC=/sbbs/exec make symlinks³⁾
8. $ SBBSCTRL=/sbbs/ctrl /sbbs/exec/jsexec update.js

If you want to build a stable release, replace the archive filenames above with valid release filenames:

1. replace sbbs_src.tgz with ssrc319b.tgz
2. replace sbbs_run.tgz with srun319b.tgz

On systems that are not properly supported by SpiderMonkey, you may be need to make use of a vendor supplied version. Doing so is not recommended or well supported, but it may be the only way to get Synchronet running on some platforms. The following steps have been reported to work on Debian Squeeze (6.0) armel (ARMv5te, EABI) on a Marvell Sheevaplug dev kit.

1. $ apt-get install libmozjs185-dev
2. Add JSINCLUDE=/usr/include/js JSLIB=mozjs185 to your make command line

On OpenBSD 5.5-current on 64-bit UltraSPARC:

1. $ pkg_add -r spidermonkey-1.9
2. $ ln -s /usr/local/lib/libspidermonkey.so.0.0 /usr/local/lib/libspidermonkey.so
3. Add JSINCLUDE=/usr/local/include/js to your make command line.

• The following error indicates that you failed to install the libncurses-dev (or libncursesw5-dev) prerequisite:

  fatal error: curses.h: No such file or directory

• The following error indicates that you failed to install the libnspr4-dev prerequisite:

  configure: error: your don't have NSPR installed or your version is too old

• Errors such as “C++ cannot create executables” and many others are generally caused by missing prerequisites.

• The following errors occur when building the Mozilla JavaScript library (libmozjs), are normal and can be safely ignored:

  /bin/sh: 1: autoconf-2.13: not found
  GNUmakefile:52: recipe for target '../build/../../src/../3rdp/gcc.linux.x64.debug/mozjs/lib/libmozjs185-1.0.a' failed
  make[1]: [../build/../../src/../3rdp/gcc.linux.x64.debug/mozjs/lib/libmozjs185-1.0.a] Error 127 (ignored)

• The following error indicates you specified a symlinks make target without the SBBSCTRL or SBBSEXEC environment variable set.

  make: *** No rule to make target 'symlinks'.  Stop.

• The following error indicates you specified an install make target without the SBBSCTRL or SBBSEXEC environment variable set.

  make: *** No rule to make target 'install'.  Stop.

• The following compilation error indicates that the wide character variant of the ncurses library has not been installed:

  error: unknown type name 'wint_t'

• The following error indicates the Synchronet libraries (shared objects) are not in your system's library search path or in the directory from which sbbs was built. Set the LD_LIBRARY_PATH environment variable to point to your Synchronet exec directory to resolve:

  sbbs: error while loading shared libraries: libsbbs.so: cannot open shared object file: No such file or directory

Since both of the above installation methods create symlinks to (rather than copy) your Synchronet library and executable files from your Synchronet build directories to your Synchronet exec directory, you must not delete (or “clean”) your build directories or else Synchronet (e.g. sbbs) and its utilities will not run until you rebuild them.

Both of the above build installation methods build a “release” (or non-debug) version of the Synchronet library and executable files. If you won't be using a debugger (e.g. gdb) to debug Synchronet (e.g. root-cause and report or fix bugs in the source code), then you probably should run the “release” binaries as they will be smaller and faster.

If you wish to build debug binaries, add DEBUG=1 to the make command-lines in the above steps.

Debug and release builds files are generated in separate output directories. If you created symlinks to your executables (i.e. specified SYMLINK=1 on the first make invocation) and switched between release and debug builds, you will need to remove or replace the symlinks in your Synchronet exec directory; this can be achieved using the symlinks build target of the src/sbbs3/GNUmakefile.

Run make gtkutils in the src/sbbs3 directory to build the GTK utilities (e.g. gtkmonitor). Add the install or symlinks target to the command-line to get the GTK utilities symlinked or copied into your Synchronet exec directory.

As of October 8th, 2011, we are including the complete SpiderMonkey (JavaScript-C) library 1.8.5 source code in the Synchronet Source Repository (under 3rdp/dist) and the src/sbbs3/GNUmakefile will build it automatically. You should now not need to specify a JSLIB= value on your make command-lines.

Compiling of the 3rd party package providing mozilla's JavaScript support seems to need an extra flag passed to it, at least for OpenBSD 4.9-5.x running on i386. When doing the initial make, try it with EXTRA_JS_CONFIGURE_ARGS=–disable-tracejit to get the process a little further along.

The make-based build system is a complex and magical beast. Changing it's behaviour though environment variables such as CFLAGS or twiddling the various undocumented knobs is not supported. If you do fiddle with the knobs and something breaks, you will be expected to support yourself regarding these changes... ie: the answer you are likely to get from the devs is “don't do that then”. Partial documentation can be found here: options

Some third parties make unsupported tarballs available from their own sites. Using them is not recommended or supported. Whenever possible you should build yourself.

1. # export SBBSCTRL=/sbbs/ctrl
2. # /sbbs/exec/scfg

See nix for more details on configuring the Synchronet initialization file (ctrl/sbbs.ini) for Unix/Linux.

Choose one mode (Console or Daemon):

You can manually run the Synchronet sysop console (somewhat interactive, but not usually preferred):

1. # /sbbs/exec/sbbs

Most of what is displayed in the console is not logged to disk in this mode.

You have some monitoring and control options from the console command prompt. Hit ? for a menu of available commands (e.g. Q to quit, stopping Synchronet).

You can install Synchronet to run as a daemon (background service, this is usually preferred).

You must be 'root' or have sudo permissions to install daemons on Unix/Linux.

Modern Debian-based Linux systems (including Ubuntu) use systemd to control (e.g. start/stop) and monitor system services (daemons). See systemd for detailed instructions on configuring Synchronet as a daemon that is started automatically and controlled via systemd.

If using an older Debian-based Linux which still uses a SysV/init.d daemon/service control system, you should use either of the following methods to add the Synchronet system service to your startup configuration for the sbbs daemon to start automatically during system startup:

# insserv -v sbbs

or:

# update-rc.d sbbs enable 2 3 4 5

If using a Red Hat based Linux (e.g. Fedora), you may need to add the Synchronet system service to your startup configuration for the sbbs daemon to start automatically during system startup:

# chkconfig --add sbbs

1. # cd /etc/init.d
2. # wget https://gitlab.synchro.net/main/sbbs/-/raw/master/install/init.d/sbbs or sbbs.debian or sbbs.gentoo
3. # chmod +x sbbs
4. # /etc/init.d/sbbs start

See syslog, umonitor, gtkmonitor and node for details on options for monitoring the Synchronet daemon while it's running in the background:

# /etc/init.d/sbbs status
Synchronet BBS services status: [running]
PID(s): 25171

1) Get the Synchronet service run script (init file) from here.

2) Copy the run script (sbbs) into your /usr/local/etc/rc.d directory

3) Set up the sbbs settings: In one of /etc/rc.conf, /etc/rc.conf.local, or /etc/rc.conf.d/sbbs, add the line:

 sbbs_enable=YES      # Required to run Synchronet

4) In one of the files from step three, add appropriate lines from the following (Defaults are shown here):

 sbbs_flags=""                        # Additional command-line flags
 sbbs_pidfile="/var/run/sbbs.pid"     # Path of pid from your .ini
 sbbs_dir="/sbbs/"                    # Root sbbs path
                                      # The rest of the sbbs_*dir derive
                                      # from this be default
 sbbs_ctrldir="${sbbs_dir}/ctrl/"
 sbbs_execdir="${sbbs_dir}/exec/"
 sbbs_program="${sbbs_execdir}/sbbs"  # Synchronet binary
 sbbs_procname="${sbbs_program}"      # Process name as seen by ps(1)
 sbbs_shell="/bin/sh"                 # SHELL variable
 sbbs_user="root"                     # User to START sbbs as.  If this is
                                      # not root, you cannot bind low ports
 sbbs_group="wheel"                   # Group to start sbbs as

5) Start the Synchronet system service (FreeBSD 5.x+):

# /usr/local/etc/rc.d/sbbs start

For most systems, the BBS must either have write access to the sound card via /dev/dsp, or run as root to page the SysOp. FreeBSD supports an alternative method which requires one of the following:

One of:

1. A custom kernel with the following option in the config device speaker
2. The speaker module loaded by either:
   1. Running kldload speaker
   2. The line speaker_load=“YES” in /boot/loader.conf file

/dev/speaker should be read/writeable by the user the BBS runs as.

Updating/synchronizing the source files:

1. If you already have the Synchronet Git repository cloned to your local system, fetch and merge any upstream changes:

$ git -C /sbbs/repo pull

Or If you do not already have the Git repository cloned, clone it to your sbbs/repo directory:

$ git clone https://gitlab.synchro.net/main/sbbs.git /sbbs/repo

Or download the latest source code and 3rd party library files and extract into your sbbs/repo directory tree:

$ mkdir /sbbs/repo; cd /sbbs/repo
$ wget ftp://vert.synchro.net/Synchronet/sbbs_src.tgz
$ tar -xzf sbbs_src.tgz

2. Rebuild Synchronet (replace symlinks with install if you prefer to copy executable and library files to your exec directory):

$ cd /sbbs/repo/src/sbbs3; make RELEASE=1 symlinks

Or if you're using setcap to start sbbs as a Linux non-root user:

$ cd /sbbs/repo/src/sbbs3; make RELEASE=1 setcap symlinks

If you get the error no rule to make target 'symlinks' or 'install', this is an indication that you do not have either the SBBSCTRL or SBBSEXEC environment variable set

3. Perform the steps listed here to update the run-time files (e.g. text.dat).

4. Shutdown and re-run sbbs (when daemonized):

$ systemctl restart sbbs

or:

$ service sbbs restart

or:

$ /etc/init.d/sbbs restart 

Occasionally, you may need to perform a clean rebuild. A clean build can generally be achieved by going to the src/ directory and executing:

./cleanall.sh RELEASE=1

Note:
If you elect to build debug binaries (instead of release binaries), then you'll need to exclude the RELEASE=1 portion from the cleanall.sh command. Otherwise, you'll be cleaning the *.release output directories when you really need to be cleaning the *.debug output directories. Likewise, if you're building and running release binaries, then you need to include the RELEASE=1 portion on the cleanall.sh commands as well. Alternatively, you can set your default build type in the file localdefs.mk. The localdefs.mk file should be created by you in either in the src/build directory (to apply to all builds), or within each directory you run make:

localdefs.mk

RELEASE=1

Now that you've completed the installation, move on to the initial setup instructions.

• Configuring Synchronet for Unix/Linux
• syslog
• umonitor
• gtkmonitor
• Prerequisites
• Installing Synchronet as your UNIX mail system
• Installing ANSI-BBS Terminal Capabilities
• How to run sbbs for FreeBSD as a non-root user
• How to run sbbs for Linux as a non-root user
• How to use GDB to debug sbbs
• How to install sbbs on Raspbian (Raspberry Pi OS)
• How to start sbbs from systemd
• Use DOS Doors with sbbs on Linux
• Development Tags