/[LeafOK_CVS]/lbbs/INSTALL.md
ViewVC logotype

Diff of /lbbs/INSTALL.md

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.20 by sysadm, Sat Nov 22 06:44:55 2025 UTC Revision 1.32 by sysadm, Sat Jan 10 06:53:26 2026 UTC
# Line 1  Line 1 
1  Installation  # Installation
 ==================  
 To install LBBS on Linux (e.g. Debian 13, CentOS Stream 10), please perform the following steps:  
   
 0) Prerequisite    
    Follow README.md under [leafok_bbs](https://github.com/leafok/leafok_bbs) to initialize the database structure shared by both web version and telnet version.    
    It is highly recommended to finish the configuration steps of web version first and make sure those features could work properly.  
   
 1) Common requirements    
    gcc >= 14.2    
    autoconf >= 2.68    
    automake >= 1.16    
    libssh >= 0.11    
    pcre2 >= 10.38    
    php >= 8.2    
    mysql >= 8.4    
   
 3) Extract the source files from a tarball or export from GitHub    
    Run the following command to set up the autoconf/automake environment,    
    autoreconf --install --force  
   
 4) Compile source files    
    export LBBS_HOME_DIR=/usr/local/lbbs    
    (For Linux)    
    ./configure --prefix=$LBBS_HOME_DIR    
    (For MSYS2 with MinGW-w64 toolchain)    
    ./configure --prefix=$LBBS_HOME_DIR --disable-shared PKG_CONFIG_PATH=/mingw64/lib/pkgconfig/    
    make    
   
 5) Create user and group    
    sudo useradd bbs  
   
 6) Install binary files and data files    
    sudo make install    
    chown -R bbs:bbs $LBBS_HOME_DIR  
   
 7) Modify following configuration files    
    Default configuration files is saved as *.default, you should rename them first.    
    $LBBS_HOME_DIR/conf/bbsd.conf    
    $LBBS_HOME_DIR/conf/badwords.conf    
    $LBBS_HOME_DIR/utils/conf/db_conn.conf.php    
   
 8) Copy CA cert file of MySQL server to $LBBS_HOME_DIR/conf/ca_cert.pem    
   
 9) Generate menu configuration file with section data by running the script    
    sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_section_menu.php    
    sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_ex_list.php    
   
 10) Create SSH2 RSA certificate    
    ssh-keygen -t rsa -C "Your Server Name" -f $LBBS_HOME_DIR/conf/ssh_host_rsa_key  
   
 11) Startup    
    sudo -u bbs $LBBS_HOME_DIR/bin/bbsd  
   
 12) (Optional) Set up systemd    
    Create your own /usr/lib/systemd/system/lbbs.service from the sample at conf/lbbs.service, and make any change if necessary.    
    Reload daemon config and start the service.    
   
 13) (Optional) Set up logrotate    
    Create your own /etc/logrotate.d/lbbs from the sample at conf/lbbs.logrotate, and make any change if necessary.    
    Restart logrotate service.    
   
 14) Cleanup on abnormal service termination    
    In case of any unexpected failure or improper operation which results in abnormal termination of lbbs process, manual cleanup of shared memory / semaphore might be required before re-launch the process. Run the following command to check first:    
    sudo -u bbs ipcs    
    There should be no item owned by bbs. Otherwise, run the following command to cleanup:    
    sudo -u bbs ipcrm -a  
2    
3    The Chinese version of this installation guide is available at [INSTALL.zh_CN.md](INSTALL.zh_CN.md).
4    
5    To install LBBS on Linux (e.g., Debian 13, CentOS Stream 10), please perform the following steps:
6    
7    ## 0. Prerequisites
8    
9    Follow the instructions in [leafok_bbs](https://github.com/leafok/leafok_bbs) README.md to initialize the database structure shared by both the web and telnet versions.
10    
11    It is highly recommended to complete the web version configuration steps first and ensure those features work properly.
12    
13    ## 1. Common Requirements
14    
15    - gcc >= 13.3
16    - autoconf >= 2.68
17    - automake >= 1.16
18    - php >= 8.2
19    - mysql >= 8.4
20    
21    ### Distribution-Specific Packages
22    
23    **Debian / Ubuntu:**
24    ```bash
25    sudo apt-get install -y libssh-dev libsystemd-dev
26    ```
27    
28    **CentOS / RHEL:**
29    ```bash
30    sudo dnf install -y libssh-devel systemd-devel
31    ```
32    
33    **MSYS2 with MinGW-w64 toolchain:**
34    ```bash
35    pacman -S --needed msys2-runtime-devel libssh libssh-devel pcre2-devel mingw-w64-x86_64-libiconv mingw-w64-x86_64-libmariadbclient
36    ```
37    
38    ## 2. Extract Source Files
39    
40    Extract the source files from a tarball or export from GitHub.
41    
42    Run the following command to set up the autoconf/automake environment:
43    ```bash
44    autoreconf --install --force
45    ```
46    
47    ## 3. Compile Source Files
48    
49    ```bash
50    export LBBS_HOME_DIR=/usr/local/lbbs
51    ```
52    
53    **For Linux:**
54    ```bash
55    ./configure --prefix=$LBBS_HOME_DIR
56    ```
57    
58    **For MSYS2 with MinGW-w64 toolchain:**
59    ```bash
60    ./configure --prefix=$LBBS_HOME_DIR --disable-shared PKG_CONFIG_PATH=/mingw64/lib/pkgconfig/
61    ```
62    
63    ```bash
64    make
65    ```
66    
67    ## 4. Create User and Group
68    
69    ```bash
70    sudo useradd bbs
71    ```
72    
73    ## 5. Install Binary and Data Files
74    
75    ```bash
76    sudo make install
77    chown -R bbs:bbs $LBBS_HOME_DIR
78    ```
79    
80    ## 6. Modify Configuration Files
81    
82    Default configuration files are saved as `*.default`. Copy and rename them first:
83    
84    ```bash
85    cd $LBBS_HOME_DIR
86    cp conf/bbsd.conf.default conf/bbsd.conf
87    cp conf/bbsnet.conf.default conf/bbsnet.conf
88    cp conf/badwords.conf.default conf/badwords.conf
89    cp utils/conf/db_conn.conf.php.default utils/conf/db_conn.conf.php
90    ```
91    
92    Then edit each file to match your environment:
93    
94    ### bbsd.conf
95    Key settings to adjust:
96    - `db_host`, `db_username`, `db_password`, `db_database`: MySQL connection details
97    - `bbs_server`, `bbs_port`, `bbs_ssh_port`: Network settings
98    - `bbs_name`: Your BBS name
99    - `bbs_max_client`: Maximum concurrent connections (adjust based on server capacity)
100    
101    ### db_conn.conf.php
102    Set the database connection parameters:
103    - `$DB_hostname`, `$DB_username`, `$DB_password`, `$DB_database`
104    
105    ### bbsnet.conf & badwords.conf
106    Review and customize as needed for your BBS policies.
107    
108    ## 7. Copy MySQL CA Certificate
109    
110    Copy the MySQL server's CA certificate file to `$LBBS_HOME_DIR/conf/ca_cert.pem`.
111    
112    ## 8. Generate Menu Configuration Files
113    
114    Run the following scripts to generate menu configuration files with section data:
115    
116    ```bash
117    sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_section_menu.php
118    sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_ex_list.php
119    sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_top.php
120    ```
121    
122    ## 9. Create SSH2 Certificates
123    
124    Generate SSH host keys for the SSH server component. The `-N ""` flag sets an empty passphrase for the keys (required for automated service startup).
125    
126    ```bash
127    ssh-keygen -t rsa -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_rsa_key
128    ssh-keygen -t ed25519 -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_ed25519_key
129    ssh-keygen -t ecdsa -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_ecdsa_key
130    ```
131    
132    ## 10. Startup
133    
134    ```bash
135    sudo -u bbs $LBBS_HOME_DIR/bin/bbsd
136    ```
137    
138    ## 11. (Optional) Set Up systemd
139    
140    Create your own `/usr/lib/systemd/system/lbbs.service` from the sample at `conf/lbbs.service`, and make any necessary changes.
141    
142    Reload daemon configuration and start the service.
143    
144    ## 12. (Optional) Set Up logrotate
145    
146    Create your own `/etc/logrotate.d/lbbs` from the sample at `conf/lbbs.logrotate`, and make any necessary changes.
147    
148    Restart the logrotate service.
149    
150    ## 13. Cleanup on Abnormal Service Termination
151    
152    In case of unexpected failure or improper operation resulting in abnormal termination of the LBBS process, manual cleanup of shared memory/semaphore might be required before relaunching the process.
153    
154    ### When Cleanup is Needed
155    - After a crash or force-kill of the `bbsd` process
156    - If `bbsd` fails to start with "shared memory already exists" errors
157    - When `ipcs` shows resources owned by user `bbs`
158    
159    ### Checking for Orphaned Resources
160    First, check for any remaining shared memory segments or semaphores:
161    ```bash
162    sudo -u bbs ipcs
163    ```
164    
165    Look for entries in the "SHM" (shared memory) and "SEM" (semaphore) sections where the "OWNER" is `bbs`.
166    
167    ### Cleaning Up
168    If resources exist, remove them with:
169    ```bash
170    sudo -u bbs ipcrm -a
171    ```
172    
173    This removes all shared memory and semaphore resources accessible to the `bbs` user.
174    
175    ## 14. Docker Installation (Alternative Method)
176    
177    For containerized deployment, LBBS provides Docker support.
178    
179    ### Building from Source
180    To build the Docker image from source code:
181    ```bash
182    docker compose up --build -d
183    ```
184    
185    ### Using Pre-built Images
186    To use pre-built images from Docker Hub:
187    ```bash
188    docker compose pull
189    docker compose up -d
190    ```
191    
192    ### Configuration for Docker
193    When using Docker, you still need to configure LBBS appropriately:
194    
195    1. **Configuration Files**: Create and customize the configuration files as described in Step 6.
196    2. **Database Connection**: Ensure `db_conn.conf.php` points to your MySQL server (which should be accessible from the container).
197    3. **Port Mapping**: By default, Docker Compose maps:
198       - SSH port: 2322 → 2322 (container)
199       - Telnet port: 2323 → 2323 (container)
200      
201       Adjust these in `docker-compose.yml` if needed.
202    4. **Persistent Data**: The `data/` and `conf/` directories are mounted as volumes for persistence.
203    
204    ### Docker Compose Management
205    - Start: `docker compose up -d`
206    - Stop: `docker compose down`
207    - View logs: `docker compose logs -f`
208    - Restart: `docker compose restart`
209    
210    For more details, refer to the `docker-compose.yml` file and Docker documentation.

Legend:
Removed lines/characters  
Changed lines/characters
  Added lines/characters
webmaster@leafok.com
 ViewVC Help
Powered by ViewVC 1.3.0-beta1