ko_center System Administrator Documentation

Version: v0.70 (2026-08-01)
Type: PHP/Perl Web Application (Single-File Architecture)
Primary File: /os/ai/io/ko_center.php (16,322 lines, 205 functions)
Database: SQLite 3 (ko_center.db3, ~39.6 MB)
Web Server: Apache (with PHP) or Python Flask (equivalent: ko_center.py)
Document Type: System Administrator Guide

1. System Architecture

1.1 Overview

ko_center is a single-file PHP web application that provides a centralized dashboard for managing LED indicators, database grids, knowledge base articles, hardware inventory, and various system monitoring tools.

The application follows a traditional LAMP-style architecture:

• Web Server: Apache with PHP module (or Python Flask for the equivalent Python port)
• Backend: PHP 5.x+ (uses $GLOBALS, $_SESSION, $_REQUEST, $_SERVER)
• Database: SQLite 3 via PDO
• Frontend: XHTML 1.0 Strict with inline CSS and JavaScript
• JavaScript Libraries: jQuery 1.7.2, jQuery UI 1.7.2, jqGrid 4.4.0, fg-menu

1.2 Request Flow

Browser Request
    |
    v
Apache/PHP (ko_center.php)
    |
    +--> startup()          [Initialize session, globals, paths]
    |
    +--> Parse ?q= parameter
    |       Split by "/" into options[] array
    |       options[0] = page, options[1] = action, options[2] = id, etc.
    |
    +--> Route to handler function
            |
            +--> leds_show()     - Display LED indicators
            +--> pdo_grid()      - Database grid view
            +--> leds_kb()       - Knowledge Base
            +--> leds_reports_*  - Reports (SQL, CSV, XML)
            +--> leds_config()   - Configuration
            +--> leds_login_*    - Authentication
            +--> trigger()       - Broadcast refresh
            +--> iperms()        - System utilities
            +--> ko_upload*      - File uploads
            +--> pdo_cr_*        - Table creation
            +--> pdo_insert_*    - Data insertion
            +--> ... (205 functions total)
    |
    +--> Generate HTML output
    |       html_header()   -  section
    |       html_btn_squares() - Navigation buttons
    |       [page content]
    |       html_footer()   - 
    |
    v
Browser renders HTML

1.3 Key Design Patterns

• Single-file architecture: All functionality is in one PHP file (no MVC framework, no separate controllers)
• Global state: Uses $GLOBALS for database file path, table name, log file, user info
• Session-based auth: $_SESSION['user'], $_SESSION['role'], $_SESSION['preview']
• URL-based routing: ?q=page/action/id parsed into $options[] array
• Procedural with functions: No classes, all functions are global
• Inline HTML generation: Functions return HTML strings that are concatenated and printed

2. Installation & Setup

2.1 Prerequisites

2.2 Installation Steps

Step 1: Deploy files

cp ko_center.php /var/www/html/ko_center/
cp ko_center.db3 /var/www/html/ko_center/db3/
mkdir -p /var/www/html/ko_center/images/btn
mkdir -p /var/www/html/ko_center/images/ani
mkdir -p /var/www/html/ko_center/images/fpb
mkdir -p /var/www/html/ko_center/kb
mkdir -p /var/www/html/ko_center/db3

Step 2: Set permissions

chown -R www-data:www-data /var/www/html/ko_center/
chmod 666 /var/www/html/ko_center/db3/ko_center.db3
chmod 666 /var/www/html/ko_center/ko_trigger.dat  # if using trigger feature

Step 3: Configure hosts.allow

Create or edit /var/www/html/../safer/hosts.allow:

allow all
# or format: allow user role

Step 4: Initialize database (if new install)

Access http://<host>/ko_center/ko_center.php in a browser. If the database file doesn't exist, the leds_install("new") function is called automatically, creating all core tables.

Step 5: Verify installation

Navigate to ?q=about or ?q=pdo to verify the database connection and table creation.

2.3 First-Time Install (leds_install)

The leds_install() function (line 9707) creates all database tables and inserts default data:

3. Configuration

3.1 Global Configuration Variables

All configuration is set in the startup() function (line 101) via $GLOBALS:

3.2 Configuration Settings

4. Database Administration

4.1 Database File

4.2 Database Connection

The newpdo() function (line 6595) creates SQLite connections:

function newpdo( $dbfile ) {
    $pdo = new PDO("sqlite:$dbfile");
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    return $pdo;
}

4.3 Key Database Tables

4.4 Database Maintenance Commands

# Check database integrity
sqlite3 /os/ai/io/ko_center.db3 "PRAGMA integrity_check;"

# List all tables
sqlite3 /os/ai/io/ko_center.db3 ".tables"

# Get table row counts
sqlite3 /os/ai/io/ko_center.db3 "SELECT name, (SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=m.name) FROM sqlite_master m WHERE type='table';"

# Vacuum the database (reclaim space)
sqlite3 /os/ai/io/ko_center.db3 "VACUUM;"

# Backup the database
cp /os/ai/io/ko_center.db3 /os/ai/io/ko_center.db3.backup.$(date +%Y%m%d)

# Export a table to CSV
sqlite3 -header -csv /os/ai/io/ko_center.db3 "SELECT * FROM leds LIMIT 100;" > leds_export.csv

4.5 Creating New Tables

Use the pdo_create() function (line 9785) or the pdo_cr_*() functions for table creation:

function pdo_create( $dbfile, $tblname, $sql ) {
    $pdo = newpdo( $dbfile );
    $pdo->exec("DROP TABLE IF EXISTS $tblname");
    $pdo->exec($sql);
    $pdo = null;
}

5. User & Role Management

5.1 Authentication Flow

1. User accesses ?q=login → leds_login_form()
2. User submits credentials → leds_login_validate()
3. Credentials checked against hosts.allow file
4. On success: $_SESSION['user'] and $_SESSION['role'] set
5. On failure: Login form redisplayed

5.2 Role-Based Access

The system supports the following roles (from the PHP code):

5.3 Session Variables

6. Security

6.1 Known Security Issues

6.2 Authentication

The authentication system uses a simple hosts.allow file check:

$allowflag = file_get_contents($GLOBALS['hosts_allow']);
$allowflag_fields = explode(" ", $allowflag);
$user = $allowflag_fields[2];

This is a very basic authentication mechanism. For production use, consider implementing proper password hashing and database-based authentication.

6.3 Session Security

The PHP session configuration is minimal. Consider adding:

• session_regenerate_id(true) after login
• Session timeout configuration
• Secure cookie flags (HttpOnly, Secure, SameSite)

7. Logging & Debugging

7.1 Log File Configuration

Log files are created in the ko_safer directory with a monthly naming convention:

Log file: /os/ai/io/../ko_safer/ko_center_YYYYMM.log
Example: /os/ai/io/../ko_safer/ko_center_202608.log

The log file path is constructed in startup() (line 145-148):

$yyyymm = date('Ym');
$logfil_basename = $progid . "_" . $yyyymm . ".log";
$logfil_rootpath = $document_root . "/../ko_safer";
$logfil = $logfil_rootpath . "/" . $logfil_basename;

7.2 Logging Functions

7.3 Debugging

Debug output is controlled by commented-out print statements throughout the code. To enable debugging:

1. Remove the // comment markers from debug print statements
2. Set error_reporting(E_ALL) in startup() (currently set to 0)
3. Check the log file: /os/ai/io/../ko_safer/ko_center_YYYYMM.log
4. Use ?q=about or ?q=pdo for basic diagnostics

7.4 Error Handling

The PHP error reporting is disabled (error_reporting(0) at line 107). Errors are silently suppressed. The application uses custom error messages embedded in HTML output rather than PHP exceptions.

8. Backup & Recovery

8.1 Backup Strategy

# Daily backup script
#!/bin/bash
DB="/os/ai/io/ko_center.db3"
BACKUP_DIR="/os/ai/io/backups"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR
cp $DB "$BACKUP_DIR/ko_center_$DATE.db3"
gzip "$BACKUP_DIR/ko_center_$DATE.db3"

# Keep only last 30 days
find $BACKUP_DIR -name "ko_center_*.db3.gz" -mtime +30 -delete

8.2 Recovery Procedure

1. Stop the web server
2. Copy backup file to database location:

   cp /os/ai/io/backups/ko_center_YYYYMMDD_HHMMSS.db3.gz /os/ai/io/ko_center.db3.gz

3. Decompress: gunzip /os/ai/io/ko_center.db3.gz
4. Verify integrity: sqlite3 /os/ai/io/ko_center.db3 "PRAGMA integrity_check;"
5. Set correct permissions: chown www-data:www-data /os/ai/io/ko_center.db3
6. Start the web server

8.3 Important Files to Backup

9. Maintenance Tasks

9.1 Routine Maintenance

9.2 LED Record Management

LED records use led_dttm = 'current' to mark active records. Historical records can be archived or deleted:

-- Archive old LED records
INSERT INTO leds_archive SELECT * FROM leds WHERE led_dttm != 'current';
DELETE FROM leds WHERE led_dttm != 'current';

9.3 Database Optimization

# Rebuild indexes
sqlite3 /os/ai/io/ko_center.db3 "REINDEX;"

# Analyze tables for query optimization
sqlite3 /os/ai/io/ko_center.db3 "ANALYZE;"

# Check database size
ls -lh /os/ai/io/ko_center.db3

# Check for fragmentation
sqlite3 /os/ai/io/ko_center.db3 "PRAGMA freelist_count;"

10. Troubleshooting

10.1 Common Issues

10.2 Debug Checklist

1. Check if PHP is running: php -v
2. Check if database exists: ls -la /os/ai/io/ko_center.db3
3. Check database integrity: sqlite3 ko_center.db3 "PRAGMA integrity_check;"
4. Check web server error log: tail -f /var/log/apache2/error.log
5. Check application log: ls -la /os/ai/io/../ko_safer/
6. Verify file permissions on all directories
7. Test with ?q=about to verify basic functionality
8. Test with ?q=pdo to verify database connectivity

11. File Structure & Assets

11.1 Directory Layout

/os/ai/io/
├── ko_center.php          # Main application (16,322 lines)
├── ko_center.db3          # SQLite database (39.6 MB)
├── ko_center.md           # Documentation (markdown)
├── ko_center.txt          # Documentation (text)
├── ko_center.py           # Python Flask equivalent
├── new_leds.py            # Create leds_randomus table
├── new_leds_tbl.py        # Generalized table creation script
├── cr_leds.py             # LED GIF generation script
├── ko_trigger.dat         # Trigger timestamp file (runtime)
├── prompt_*.txt           # Original task prompts
├── response_*.txt         # Response documents
├── images/
│   ├── btn/               # Button images (btn_black.gif, btn_white.gif, etc.)
│   ├── ani/               # Animated LED GIFs (ani_red0.gif, etc.)
│   ├── fpb/               # Floor plan button images
│   └── cab/               # Cabinet images
├── ko_center/
│   ├── db3/               # Additional database files
│   │   ├── ko_center_certs.db3
│   │   └── koaac_kb.db3
│   └── kb/                # Knowledge Base file storage
├── ../safer/
│   └── hosts.allow        # Authentication/authorization file
├── ../ko_safer/
│   └── ko_center_YYYYMM.log  # Monthly log files
├── js/
│   ├── jquery-1.7.2.min.js
│   ├── jquery-ui-1.7.2.custom.min.js
│   ├── fg-menu/           # fg-menu JavaScript and CSS
│   ├── jqgrid-4.4.0/      # jqGrid library
│   └── tooltip/           # Tooltip JavaScript
└── css/
    └── (theme CSS files)

11.2 Image Assets

12. PHP Function Reference

12.1 Core Functions

12.2 Database Functions

12.3 Report Functions

12.4 KB Functions

12.5 Utility Functions

12.6 AJAX Functions

13. Deployment

13.1 Apache Configuration

<VirtualHost *:80>
    ServerName ko_center.example.com
    DocumentRoot /os/ai/io

    <Directory /os/ai/io>
        Options +FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    # PHP configuration
    php_value upload_max_filesize 50M
    php_value post_max_size 50M
    php_value max_execution_time 300
    php_value memory_limit 256M

    # SQLite configuration
    php_value sqlite.assoc_case 0

    ErrorLog /var/log/apache2/ko_center_error.log
    CustomLog /var/log/apache2/ko_center_access.log combined
</VirtualHost>

13.2 Python Flask Deployment

The Python Flask equivalent (ko_center.py) can be deployed with:

# Development server
python3 /os/ai/io/ko_center.py

# Production with Gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 ko_center:app

# Production with systemd service
# Create /etc/systemd/system/ko_center.service:
[Unit]
Description=ko_center Python Web Application
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/os/ai/io
ExecStart=/usr/bin/python3 /os/ai/io/ko_center.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

13.3 Environment Variables

14. Python Flask Equivalent

A Python Flask equivalent of ko_center.php has been created at /os/ai/io/ko_center.py. Key differences from the PHP version:

Running the Python version:

python3 /os/ai/io/ko_center.py

15. API Endpoints

15.1 Query Parameter Routes

15.2 Trigger API

The trigger endpoint provides a JSON API for browser refresh coordination:

Request

GET /ko_center/ko_center.php?q=trigger[&last_check=<timestamp>]

Response

{
  "triggered": true|false,
  "timestamp": "2026-08-01 07:05:00",
  "since": "2026-08-01 07:00:00"
}

Example

# First call (no last_check)
GET /ko_center/ko_center.php?q=trigger
→ {"triggered": true, "timestamp": "2026-08-01 07:05:00", "since": ""}

# Subsequent call (no new trigger)
GET /ko_center/ko_center.php?q=trigger&last_check=2026-08-01 07:05:00
→ {"triggered": false, "timestamp": "2026-08-01 07:05:00", "since": "2026-08-01 07:05:00"}

# Another browser calls trigger
GET /ko_center/ko_center.php?q=trigger
→ Writes new timestamp to ko_trigger.dat

# First browser's poll detects the change
GET /ko_center/ko_center.php?q=trigger&last_check=2026-08-01 07:05:00
→ {"triggered": true, "timestamp": "2026-08-01 07:06:00", "since": "2026-08-01 07:05:00"}
# Browser reloads the page

Appendix A: Version History

Appendix B: Python Scripts Reference