DocBuild

Building SLASH2

This document describes how to obtain and install SLASH2.

Conventions

This document refers to all file and subdirectories relative to the root of the projects top-level source code directory. SLASH2 (slashd2/) is a subdirectory that lives inside this root.

The convention for the locate of SLASH2 runtime information is /local/$DEPLOYMENT.s2/. This directory will contain logfiles, corefiles, and SLASH2 configuration. This location can be changed by changing the $INST_BASE make setting in mk/local.mk relative to the root of the PFL source tree.

Obtaining the Source Code

There is a separately maintained repository that is only updated when a slate of regressions are known to pass, so it lags behind cutting edge development but is considered more stable. To access this repository, use:

$ git clone https://github.com/pscedu/slash2-stable
$ cd slash2-stable

Local Customizations

Local customization may be necessary to adapt the code base for a specific machine/deployment environment. Such customizations can be added to mk/local.mk:

$ cat mk/local.mk
INST_BASE=/usr/local		# defaults to /local

By default, INST_BASE defaults to /local, so it would be desirable to add /local/bin and /local/sbin to $PATH and /local/man to $MANPATH, etc.

Next, select which component(s) of SLASH2 are needed for the target machine. By default, all components (MDS, I/O, and client) are built. If any of these components is not necessary, local setting overrides can disable building of certain components. These settings can be specified in slash2/mk/local.mk.

Examples

For example, to disable building of the MDS, specify only ion and cli in local.mk:

$ cat slash2/mk/local.mk
SLASH_MODULES= ion cli

Version-tracked Site Settings

As it is desirable to version track settings for your site as well as tie such configuration management into the SLASH2 build process for having one mechanism for pushing updates to machines in a SLASH2 deployment, the SLASH2 build framework supports specification of local infrastructure.

For example, to install a deployment configuration in tandem with the rest of a SLASH2 installation:

$ cat inf/$DEPLOYMENT/Makefile
ROOTDIR=../..
include ${ROOTDIR}/Makefile.path

include ${PFLMK}

install-hook:
	@${INST} -m 644 $DEPLOYMENT.dcfg ${INST_BASE}/pfl_daemon.cfg/
	@${INST} -m 644 $DEPLOYMENT.slcfg ${INST_BASE}/$DEPLOYMENT.s2/slcfg

Here, the path inf/$DEPLOYMENT/slcfg refers to a SLASH2 deployment configuration file (slcfg) that is version tracked in a separate repository from SLASH2 or PFL, or any other PSC repository. This makes local deployment configuration management possible and easy. The PFL build framework simply run git pull in each subdirectory of the top-level inf/ subdirectory.

SLASH2 Dependencies

Most dependencies listed below require the "development" edition of the following packages:

Needed by all SLASH2 components (MDS, CLI, IOD)

• GNU make
• libgcrypt
• pkg-config
• readline
• byacc (Berkeley yacc is known to work)
• lex (GNU flex is known to work)
• ncurses

MDS-specific

• slashd (the SLASH2 MDS daemon) requires zfs-fuse, which is included in the SLASH2 distribution.
• libaio is needed by zfs-fuse.
• OpenSSL is needed by zfs-fuse.
• scons is needed to build zfs-fuse.
• sqlite3

CLI-specific

• FUSE is also packaged within the SLASH2 distribution repository and can be built with:

$ cd distrib/fuse $ ./configure $ make $ sudo make install

  <!-- ` -->

  If it is not possible to install the FUSE included in the SLASH2
  distribution, the version provided by the system will be adequate.
  It is simply recommended as the one in SLASH2 is the latest and
  reduces chances of incompatibilities/bugs from older versions or
  vendor modifications.
  In this case, specify the location of `fuse.pc` in
  `$PROJ_ROOT/mk/local.mk`:

  ```sh
$ cat mk/local.mk
PKG_CONFIG_PATH=/usr/local/fuse

Building instructions

Finally, build the SLASH2 software with gmake:

$ make build
$ sudo make install

Note: SLASH2 actually requires gmake to build, so make sure this command is specifically used on systems such as BSD that don't default to GNU make.

If the build finished without errors, congratulations on compiling the SLASH2 source code! All files will install into /local by default. Administrators may now proceed deploying SLASH2 by consulting sladm(7).

If errors were encountered, please report, providing error details and operating system information and version, to the development mailing list.

For an MDS, zfs-fuse will also need to be installed:

$ cd zfs-fuse
$ sudo make install

System reconfiguration

SLASH2 uses a system compatibility discovery mechanism similar to GNU autoconf (i.e. ./configure) offered by many common open source software projects. This compatibility information is automatically generated before the first compilation and regenerated subsequently based on heuristics when something on the build host has changed.

In the case of missing system packages, or updated system packages, etc. when it is necessary to re-perform this configuration probe (such as when ./configure would need to be rerun), this configuration should simply be removed and the build system will automatically regenerate it next time it is needed:

$ rm mk/gen-localdefs-${hostname}-pickle.mk

Recompiling/Upgrading

Updating a SLASH2 source tree should be executed from the top-level projects directory to ensure any changes made in common libraries outside the SLASH2 source root are also grabbed:

$ make up

After source modifications have been made, whether manually or after pulling updates, recompile the suite:

$ make build
$ sudo make install