

-------------------------------------------------------------------------------


General                 SMSLink Server Installation Procedure
Introduction
Documentation           Please note: The installation instructions below will
Platforms               actually build and install both the server and the
Supported_Hardware      gateway module. For configuration instructions specific
Package_Content         to the gateway module, please check this page.

                        Table of Contents
Installation
Download
Server_Install            1. Connect_the_hardware.
Client_Install            2. FreeBSD:_Configure_serial_port.
Gateway_Install           3. Configure_the_modem_(if_needed).
Upgrade                   4. Install_libmodem.
                          5. Tailor_libmodem_configuration_file.
                          6. Untar_the_SMSLink_package.
Tech Info                 7. Setup_link_with_backend_MySQL_database_(optional).
Changelog
FAQ                            1. Install_MySQL_server.
Drivers                        2. Install_MySQL_client_+_headers.
PDU_format                     3. Configure_the_server_module's_access_to_the
Bugs_/_Todo                       database.
Related_Links
                          8. Build_SMSLink_server_modules.

_Jump_to_Vim_Home_Page_        1. Customize_Makefile.
                               2. Customize_main_header_file_(optional).
                               3. The_build_process_proper.

                          9. Install_server_modules.
                         10. Include_SMS_in_the_known_services.
                         11. Copy_the_"driver_database"_to_/etc.
                         12. Tailor_the_config_file_to_your_needs.
                         13. Implement_access_control_(optional).
                         14. Create_the_inbox_directory.
                         15. Create_the_outbox_directory_(optional).
                         16. Arrange_for_the_service_to_be_started_at_boot
                             time.
                         17. Test_your_installation.

                        -------------------------------------------------------

                        Connect the hardware.

                        Assemble and connect the GSM module (power, serial and
                        aerial). Test connectivity with Minicom (or any other
                        serial communication program you feel comfortable
                        with): the parameters are likely to be 9600, N, 8, 1.
                        Type AT<cr>, you should get "OK" in return.
                        Please note: In order for this to work (as well as the
                        rest of this install procedure), your kernel should be
                        compiled with serial support (CONFIG_SERIAL -- most
                        pre-compiled kernels are). If serial support was
                        compiled as a module, that module should be loaded.
                        Then test the SIM card recognition and GSM network
                        connectivity:

                          	AT+CPIN?
                          	SIM PIN

                          	AT+CPIN=1234
                          	OK

                          	AT+CPIN?
                          	READY

                          	AT+CREG?
                          	CREG: 0,1

                        This short dialog provided the SIM card with the PIN
                        code it requested, then verified that the module did
                        attach to the GSM network. For further details on those
                        commands (and the SMS-related AT+ command set in
                        general), see your module handbook or the "GSM Modules
                        Tech Info" section on the Related_Links page.
                        -------------------------------------------------------

                        FreeBSD: Configure serial port.

                        (Please note: Failure to follow this step may lead to
                        the "lopen_mdm_line() failed" error -- please read
                        this, more specifically the note to FreeBSD users, for
                        more details about it.)
                        Edit /etc/rc.serial, and add the following line (or a
                        similar one depending on your needs, of course):

                          	modem d a 0

                        This calls the modem() function (also in rc.serial)
                        with the dialin and dialout devices (ttyd and cuaa) and
                        the specific device (ttyd0 and cuaa0). The modem
                        function sets the necessary parameters, like crtscts,
                        baud rates, etc. for the device.
                        Reboot the machine to activate the changes.
                        More details on this step at: http://www.freebsd.org/
                        doc/en_US.ISO8859-1/books/handbook/serial.html
                        Thanks a lot to Nicki_de_Wet for those valuable
                        insights.
                        -------------------------------------------------------

                        Configure the modem (if needed).

                        At this stage, you can disable the Network Registration
                        unsollicited result code, as the server program will
                        never use it anyway, and it might confuse it if
                        present.
                        At the "AT" prompt interface, issue the following
                        commands:

                          AT+CREG=0
                          AT&W

                        The first line will disable the aforementionned
                        feature, the second will save that setting to the modem
                        EEPROM, making it permanent.
                        Here, you can also take the opportunity to configure
                        your modem for the highest supported speed on the
                        serial line. A higher speed here will maximize
                        throughput later. Recommended: 19200 bps, if supported
                        by the device.

                          AT+IPR=?
                          AT+IPR=19200
                          AT&W

                        The first command queries the device for the speeds it
                        supports. The second sets it to 19200 bps, and the last
                        one commits the changes to the modem EEPROM. Please be
                        aware that you will have to reconfigure your
                        communication software before being able to save your
                        changes, since the AT+IPR command takes effect
                        immediately.
                        -------------------------------------------------------

                        Install libmodem.

                        Either grab libmodem-1.5 or higher (you can get it here
                        or there)
                        - or -
                        grab version 1.0.0 of the package from its official
                        location or from here and apply the provided patch.
                        Untar the source package and then patch it with
                        Angelo's SMS patch and mine (combined in the file
                        libmodem-1.0.0.pha.patch located here in the varia/
                        patch/ directory).
                        Then, whatever the version, proceed to install it as
                        mentionned in this package documentation.
                        -------------------------------------------------------

                        Tailor libmodem configuration file.

                        Normally called /etc/modems by default, you should
                        create a line there for each serial line(s) you'll
                        connect the GSM module(s) to. I suggest creating a
                        symlink from the original /dev/cua? device (/dev/ttyS?
                        recommended if you're on Linux kernel 2.2.x or higher)
                        to /dev/gsm (or /dev/gsm? if you plan to connect more
                        then one).
                        The location of the file is controlled by the MDMFILE
                        define, located in dial/modems.h.in, and a template
                        modems file can be found in the etc directory (relative
                        to the base of the libmodem package tree). As an
                        example, here are lines that work for me:
                        gsm0:AT::+++:30:9600:CONNECT:D:::Z:H0:0
                        gsm1:AT::+++:30:9600:CONNECT:D:::Z:H0:0
                        -------------------------------------------------------

                        Untar the SMSLink package.

                        First, grab the latest distribution tar file from the
                        download_page on this site.
                        Then, uncompress and untar this distribution package on
                        your system, for instance under /usr/src.
                        Example:

                          	$ mv smslink-0.55b.tar.gz /usr/src
                          	$ cd /usr/src
                          	$ gunzip smslink-0.55b.tar.gz
                          	$ tar -xvf smslink-0.55b.tar

                        -------------------------------------------------------

                        Setup link with backend MySQL database (optional).

                        As of version 0.55b, the SMSLink server module supports
                        the use of a backend MySQL database to store incoming
                        and outgoing (when queued) messages. This feature is
                        optional, though -- both incoming and queued outgoing
                        messages can also be stored in / as text files.
                        Should you wish to enable this feature, please follow
                        these steps to install and configure all the required
                        components.

                        Install MySQL server.

                        Please note that the back-end MySQL server doesn't have
                        to reside on the same physical host as the SMSLink
                        server module. sms_serv(1) is able to access its
                        configured database back-end over the network.
                        So, on the host of your choosing, please install the
                        MySQL server component (the details of that
                        installation are beyond the scope of this document,
                        please refer to the excellent MySQL documentation, or
                        simply select the mysql package provided by your
                        distribution). Arrange for the MySQL server component
                        to be started at this host boot time.
                        When this is done, please use the provided ./varia/
                        database/database.sql SQL script as input for the mysql
                        client. This will create the MySQL objects required by
                        SMSLink: the smsstore database and the dbschema, inbox
                        and outbox tables.
                        Example:

                          	$ cd ./varia/database
                          	$ mysql -u root -p smsstore < database.sql


                        Install MySQL client + headers.

                        On the host where the SMSLink server module will reside
                        (the host with access to the GSM serial device(s)), you
                        should install (at least) the MySQL client library and
                        header files. Those will be required in order to
                        compile the sms_serv(1) server module.
                        If you're using SuSE Linux distribution, the MySQL
                        client library and header files are provided in the
                        following packages:

                        * mysql-shared-3.23.52-44 (client lib.)
                        * mysql-devel-3.23.52-44 (header files)

                        The exact version of the package may vary, of course,
                        but use of MySQL version 3.23 or higher is required for
                        API reasons.

                        Configure the server module's access to the database.

                        Now, you should arrange for the sms_serv(1) module to
                        be granted access to the smsstore database.
                        Using the mysql client, connect to the smsstore
                        database as the admistrator (typically root), and
                        create a new user dedicated to SMSLink usage. We'll
                        assume that you called this user smslink in the rest of
                        this document (but you're free to call it any way you
                        like).
                        The newly created smslink user should be granted the
                        following rights on the smsstore database:

                        * SELECT
                        * INSERT
                        * UPDATE
                        * DELETE

                        Then, copy to /etc the default gsmdbtab file provided
                        in ./server and customize it to match your setup: it
                        should contain a single line observing the following
                        format:
                        dbserver:dbname:user:password
                        Example:

                          	wopr:smsstore:scott:tiger

                        For obvious security reasons, make sure this file is
                        owned by the user that you plan to run the sms_serv
                        module as, and chmod it 400.
                        -------------------------------------------------------

                        Build SMSLink server modules.

                        In order to start the server modules build process,
                        change directory to ./smslink-<version>/server. The
                        first step will be to make sure the Makefile there
                        matches your environment. In a second, optional step,
                        advanced users may also fine-tune the main header file.

                        Customize Makefile.

                        Edit the first part of ./smslink-<version>/server/
                        Makefile to accomodate your platform and feature
                        choices.

                        * First make sure to uncomment the line corresponding
                          to your platform (and make sure only one such line is
                          uncommented). More on supported platforms here.
                        * If you'd like to use the MySQL backend database
                          feature, make sure to uncomment the line that reads
                          SQL = -DWITH_MYSQL (beware: this requires the
                          presence of MySQL client lib. and header files on
                          this host (see above for details)).
                        * For building the server with debugging enabled, you
                          can uncomment the line that reads DEBUG = -
                          DINCL_DEBUG_CODE. Please note: as of 0.54b, the use
                          of this flag is mostly obsolete. Debugging is now
                          turned on by the -d command-line option. If, on the
                          other hand, you need a build that includes debugging
                          symbols, you can get it by invoquing make as:
                          CFLAGS=-g make.
                        * If your environment requires it (e.g. your MySQL
                          client library and / or header files are located in
                          an unusual place), please use the IEXTRA and LEXTRA
                          lines (commented out by default) to add custom
                          entries to your compiler libraries and / or include
                          files search paths.
                        * On the lines that follow, you can also customize the
                          names of the compilation chain tools. Please use with
                          care !
                        * And last, you get an opportunity to customize the
                          installation paths (/usr/local/bin and /usr/local/man
                          by default).


                        Customize main header file (optional).

                        Please note: The main header file, as shipped, should
                        fit most setups and I don't recommed first-time users
                        try to alter it in any significant way. However, when
                        more familiar with the inner working of the program,
                        those options may be of valuable help.
                        For more fine-tuning of the server modules operation,
                        you can customize some entries in the main header file
                        (server/sms_serv.h). A few usefull ones will be
                        described below. Please note that the most often used
                        ones have been added as command-line options as of
                        version 0.55b (and it is our plan to soon have all of
                        them available through some global configuration file).
                        Should you wish to make use of the "prog" feature for
                        some or all the devices, you should edit server/
                        sms_serv.h at this point and customize the line that
                        reads:

                          	#define SMS_PROG_NAME           "sms-recv.pl"

                        to match the program name you would like the incoming
                        messages to be fed to. Make sure to use the full path
                        name when the required program doesn't live in a
                        directory covered by the PATH environment variable
                        (please remember that init(8), if this will be the one
                        to start sms_serv(1), uses a minimal PATH).

                        The build process proper.

                        You can then type make to initiate the build process.
                        Depending on the platform, a few warnings might be
                        issued during the compilation phase, but those can be
                        safely ignored.
                        -------------------------------------------------------

                        Install SMSLink server modules.

                        When compiled successfully, type make install as root.
                        Note that this will install both sms_serv(1) and
                        sms2mailgw(1) (as well as all related man pages). You
                        can choose to compile only the server module by typing
                        make sms_serv, but there is no separate install target
                        (yet).
                        -------------------------------------------------------

                        Include SMS in the known services.

                        Edit your /etc/services file, and add the following
                        line:

                          sms             6701/tcp                        # SMS
                          Link Server

                        -------------------------------------------------------

                        Copy the "driver database" to /etc.

                        In order for the server program to be able to work with
                        different brands of GSM modules, some primitive form of
                        driver is now provided. The default file is found in
                        the server/ directory, and is called gsmcaps. If this
                        is a first install, or you didn't tinker with the
                        previous version of this file, just copy this file to /
                        etc. If you're using a modified version of the file,
                        please review the diffs and integrate them manually.
                        This file will NOT be installed automatically by the
                        make install procedure, in order to avoid overwriting
                        any customization of yours.
                        Should you indeed have had to customize this file,
                        please keep me posted so that I can distribute your
                        changes with the next release.
                        -------------------------------------------------------

                        Tailor the config file to your needs.

                        The config file, by default, is called /etc/gsmdevices.
                        It contains, among others, the PIN code, PUK code, and
                        caller ID of the installed SIM card. You'll obviously
                        need to change those to match your own SIM. A template
                        file is located in the ./server directory, but it will
                        NOT be copied in place by the installation process (to
                        avoid overwriting the existing config when upgrading).
                        You should also consider which feature you want to
                        enable for the device. Those features are controlled by
                        the flags that make up the last field of each device
                        record (as of version 0.54b). By default (if left
                        empty), the only feature enabled are "poll" (poll the
                        device at interval to check for incoming messages) and
                        "inbox" (store those messages in an inbox file). Other
                        selectable features are "dd" (attach a dedicated daemon
                        the the device), "init" (initializes the device once,
                        thereby saving time on future send), "prog" (feed the
                        incoming messages to a program), "fast" (use "fast
                        modem response") and "r4" (causes all messages to be
                        read from the device, not just unread ones). Please
                        refer to gsmdevices(5) for more details on those flags
                        and their effects.
                        It is also likely that you'll want to customize the
                        value of the "PINpause" parameter. But before doing it,
                        I suggest you read the special coverage I gave this
                        feature in question_2.1.10 of the accompanying FAQ.
                        WARNING: The format of this file changed between
                        version 0.44b and version 0.46b of the server module,
                        and again between version 0.46b and version 0.48b.
                        Version 0.54b added an optional last field to the
                        record. Then version 0.55b changed the format again by
                        adding the "PINpause" parameter. Please refer to
                        gsmdevices(5) or the header of the example gsmdevices
                        file provided in the server/ source directory for more
                        details on the file format.
                        -------------------------------------------------------

                        Implement access control (optional).

                        Create a file called (by default) /etc/gsmaccess. It
                        will contain a list of the IP addresses of the networks
                        or machines that are allowed to connect to the server.
                        In this file, lines beginning with a '#' are treated as
                        comments. Blank lines are ignored. In case the file is
                        not present, no access control will be implemented. The
                        install process DOES NOT copy the template to /etc by
                        default meaning no access control is put in place
                        unless you copy it yourself.
                        Access control, when enabled, defaults to deny.
                        Anything not specifically allowed is denied. So make
                        sure that the /etc/gsmaccess file is not left empty and
                        that each entry follows the stated format (invalid
                        entries are ignored). See gsmaccess(5) for format
                        details and examples.
                        -------------------------------------------------------

                        Create the inbox directory.

                        Create a directory called smslink under /var/spool (see
                        the define called MBOX_FILE in sms_serv.h) and make
                        sure the rights and ownership are consistent with the
                        user the server will run as and the other external
                        applications that will have to access it (root:root,
                        0750, for instance).
                        The server component will create a file called inbox
                        there.
                        -------------------------------------------------------

                        Create the outbox directory (optional).

                        Note: This step is required only for versions 0.55b or
                        greater of the server, and then only when you want to
                        make use of the queueing feature in "file" mode.
                        You should now have a directory called smslink under /
                        var/spool already (see the_previous_installation_step).
                        In this directory, create a sub-directory called outbox
                        (same rights and ownership as its parent). The server
                        component will use it to store queued items when / if
                        you use the "file" queueing method.
                        Once this is done, in order to enable the queueing
                        feature in the server, you need to either edit ./
                        server/sms_serv.h and set OBCHKINTERVAL to a non-zero
                        value (the elapsed time in seconds between two outbox
                        queue runs), or start the server with the -o / --
                        obchkinterval command-line option followed by the
                        interval in seconds.
                        -------------------------------------------------------

                        Arrange for the service to be started at boot time.

                        Edit your init scripts to have the service(s) started
                        at boot time. Normally, it requires root capabilities
                        to successfully start the service, as only root can
                        access the GSM device by default. This is not a problem
                        since it will most likely be started by init. You might
                        consider it even safer to create a special group, grant
                        this group rw access to the serial device the GSM
                        module is attached to, and then setgid the binary to
                        this group.
                        A sample System V init script and its accompanying
                        configuration file are now provided in the archive,
                        below ./varia/scripts/SuSE/. They were designed with
                        SuSE Linux 9.3 Pro in mind, but can certainly be used
                        (at least as a starting point) for other distributions
                        as well.
                        In the case of SuSE, simply copy ./varia/scripts/SuSE/
                        init.d/smslink to /etc/init.d and ./varia/scripts/SuSE/
                        sysconfig/smslink to /etc/sysconfig. You may wish to
                        edit the default values provided in /etc/sysconfig/
                        smslink to better suit your needs. The init script will
                        take care of starting both daemons (sms_serv(1) and
                        sms2mailgw(1)). Test that its working properly by
                        invoquing the script manually (you can have a look at
                        your syslog file to check that both modules start
                        successfully):

                          # /etc/init.d/smslink start
                          [...]
                          # /etc/init.d/smslink stop

                        Once you're satisfied that the script is working
                        properly, you can use the following command to make
                        sure that the startup and shutdown will happen
                        automatically:

                          # cd /etc/init.d
                          # insserv smslink

                        If you're using another distro, please adapt those
                        directions accordingly.
                        -------------------------------------------------------

                        Test your installation.

                        Now that the server is installed, configured and
                        started, try to connect to it. The easiest way is to
                        telnet to it (with a telnet client supporting "line
                        mode" -- Linux is perfect, of course). Type:

                          	$ telnet my-server 6701

                        You should be greeted with the SMS> prompt. Reproduce a
                        session similar to the following:

                          	SMS> set dest = 12345 (your mobile phone number)
                          	Ok
                          	SMS> set user = "yourself"
                          	Ok
                          	SMS> set msg = "Hello GSM World!"
                          	Ok
                          	SMS> send

                        Now sit back and watch...
                        That's all, Folks...

-------------------------------------------------------------------------------

Last Modified: September 29th, 2006.
     _philipa_STRUDEL_scarlet           _SourceForge_Logo_
     PUNKT_be_

