|dim_STAT User's Guide. by Dimitri|
dim_STAT installation package is delivered generally as TAR archive (dim_STAT.tar) or already "untared" on CD support.
Before install: Verify your disk space - you will need ~50MB for initial install, mostly to host Web Server and Database Server data. Database volume will grow according size of your future STAT collections and Web directory may grow with your reports, so be large at once and reserve enough space for your data...
During installation: new user "dim" and group "dim" will be created. User "dim" is the owner of dim_STAT database and Web server. In case you have some special rules or restrictions on your system, you may create it by yourself before, as well choose another user and group names according your system policy.
As root user, unload the tar archive somewhere and start installation script:# cd /tmp # tar xvf /path_to_tar/dim_STAT.tar # cd dim_STAT-INSTALL # # INSTALL.sh
During installation you'll be asked to confirm your host IP address (found automatically), host and domain name, verified that user "dim" already exist on the system (in other case it'll be created), asked about WebX and home directory (Web Server, Database Server, Administration and Client scripts, etc.), Port numbers...
NOTE: Since v.7.0 installation is simplified:
- no more /apps link created
- dim_STAT user owner may be different from 'dim'
- only 3 application directory:
- WebX (def: /opt/WebX)
- Home (def: /apps)
- Temp (def: /tmp)
If you are not sure about meaning of some values - leave them by default, the main parameter during installation is directory names.
NOTE: WebX is a main interpreter (or execution engine, etc.), so it interprets all application script files and _absolutely_ need fixed/trusted root directory. Otherwise, anyone may execute whatever you want from your machine (ex. /etc/passwd to crack logins, etc.). So, it's a first step protection for its root directory: you may choose one from 3 available names (hey, 3 choices anyway! better then one :)) Also, WebX engine itself is very small (few MB) and not growing, so I don't think it'll makes any problem for you...
After (default) installation, dim_STAT software will be distributed in the following way on your system:- /WebX, /opt/WebX or /etc/WebX - WebX main directory: you choose from 3 possible placements - /apps - default dim_STAT home directory | +-- /ADMIN - administration scripts (start/stop dim_STAT Server, BatchLOAD, etc.) | +-- /mysql - MySQL database server main directory | +-- /httpd - Apache Web server directory | +-- /client - client collect script(s) | +-- /Java2GIF - Java applet graph to GIF convertor | +-- /htmldoc - HTML to PDF converting tool | +-- ... - there may be other directories depending on dim_STAT release :))
NOTE: in all next examples let's suppose your home directory is '/apps' to simplify things.
Since v.8.1 there is a silent (auto) install feature integrated into INSTALL.sh script. It may be very useful in case you need to automate or package installation on your servers.
To activate it, you need just use '-Auto yes' option.
Then more options if you want to have any setting different from default:
- -HOST `hostname`
- -IP ip_address
- -USER dim
- -GROUP dim
- -WebX_DIR /opt/WebX
- -TEMP_DIR /tmp
- -HOME_DIR /apps
- -HTTP_PORT 80
- -DB_PORT 3306
- -STAT_PORT 5000
- -USERADD yes -- add user/group
- -AutoLink yes -- make auto-start links in /etc/rc*.d
Examples:Default install: # ./INSTALL.sh -Auto yes With customized Home: # ./INSTALL.sh -Auto yes -HOME_DIR /export/home/apps/dim_STAT With existing User: # ./INSTALL.sh -Auto yes -User stat -Group staff -ADDUSER no -HOME_DIR /staff/stat etc...
|Starting Web and Database servers|
As you saw before, administation scripts are placed in /apps/ADMIN:# cd /apps/ADMIN # dim_STAT-Server startTo stop servers:# cd /apps/ADMIN # dim_STAT-Server stopNOTE: since v.7.0 global dim_STAT-Server script replaced separated httpd/mysql scripts. This global script now checks before stop/start action if there are any active collect present and restart them automatically during next startup. Also, if shutdown was not done properly, datafile check will be executed on all databases automatically before any action...
At any moment you may see any active connections in the database:$ su - root # /apps/mysql/bin/mysql -S/apps/mysql/data/mysql.sock.YOUR_PORT_NO mysql> mysql> show processlist; +------+------+-----------+----------+---------+-------+-------+------------------+ | Id | User | Host | db | Command | Time | State | Info | +------+------+-----------+----------+---------+-------+-------+------------------+ | 3 | dim | localhost | Mind | Sleep | 18 | NULL | NULL | | 4 | dim | localhost | Mind | Sleep | 17 | NULL | NULL | | 5 | dim | localhost | Mind | Sleep | 2 | NULL | NULL | | 6 | dim | localhost | Mind | Sleep | 1 | NULL | NULL | | 7 | dim | localhost | Mind | Sleep | 2 | NULL | NULL | | 8 | dim | localhost | Mind | Sleep | 16 | NULL | NULL | | 9 | dim | localhost | Mind | Sleep | 104 | NULL | NULL | | 10 | dim | localhost | Mind | Sleep | 1 | NULL | NULL | | 11 | dim | localhost | Mind | Sleep | 0 | NULL | NULL | | 53 | dim | localhost | UPC | Sleep | 108 | NULL | NULL | | 54 | dim | localhost | UPC | Sleep | 103 | NULL | NULL | | 56 | dim | localhost | UPC | Sleep | 115 | NULL | NULL | | 57 | dim | localhost | UPC | Sleep | 118 | NULL | NULL | | 58 | dim | localhost | UPC | Sleep | 112 | NULL | NULL | | 59 | dim | localhost | UPC | Sleep | 105 | NULL | NULL | ...and even kill any of them (be very careful, however :))mysql> kill 57; mysql> quit Bye # #
MySQL is very easy in administration. However, based on the past user's experience, here are some tips...
Use separated databases as soon as you can: it's much more easier for administration, avoids any possible future activity conflicts, etc.
Limitation in number of connections: each MySQL connection uses 5 file descriptors. It means, with default (often) 1024 per process file description limitation we can't create more than ~200 connections on multi-threaded MySQL server. (Note: each STAT is a single connection). In case you need more connections (several hosts, many stats, etc), check first values of your /etc/system parameters : rlim_fd_cur and rlim_fd_max, next in file /apps/mysql/mysql.server replace default 200 value by a new one.
Accident Power OFF on your machine: It's very possible some of MySQL index files will be corrupted. Since v.7.0, dim_STAT-Server script will run data check automatically. But it's always useful to know how to do it by hand. Stop mysql and recheck/rebuild your indexes first and restart your database server next:# cd /apps/ADMIN; # stop.MySQL # cd /apps/mysql/data/Your_database_name # /apps/mysql/bin/myisamchk -r *.MYI # cd /apps/ADMIN; # start.MySQL
No more disk space: just add space if it possible :)). Collect part in dim_STAT is done in way to "keep flow" in any case, so nothing will be stopped in case of errors. Once you added space, collects will continue (you probably will get just some holes during this period :))
Get a backup/copy of your collects in the fastest way: one of the great features of MySQL is its support of cross-platform data compatibility. It means, the same database files may be moved from Solaris machine and successfully reused on Linux laptop (for example). And in any case, copy of the whole database to another machine will be much more faster than export and following import collects via flat files (except you want to move just a very small amount of data from a very big database).
Fine, but can we do it ONLINE? - Yes! :)) In case nobody use your database, you may just stop and start database server to be sure to flush all data and close files properly (there are, of course, some less radical solutions, but this one is more evident for anybody :)). In case your database is under continuous usage - just stop database server (as it was described below, no connection will be lost), finish your copy, and restart the server next:# cd /apps/ADMIN; # stop.MySQL # cp -rp /apps/mysql/data/Your_Database_Name /your_backup # start.MySQL
Delete database: there is no way to delete database via Web interface (I don't like deleting generally :)), delete by error is so common thing... So, if you really need to delete your database the only way is:# rm -rf /apps/mysql/data/Your_Database_Name
Several MySQL instances on the same host: was one of the hot problem as conflicting with already installed and running servers you make new troubles in existing system. I've found solution to completely isolate dim_STAT database from existing instances but the price is - more complexity in simple things. Tool uses its own parameters for TCP/IP port and UNIX sockets, so, for example, to connect locally to your database server instead of usual:you should use:# /apps/mysql/bin/mysql DatabaseName
where PortNO is TCP/IP port number given to your database server during installation.# /apps/mysql/bin/mysql -S/apps/mysql/data/mysql.sock.PortNO DatabaseName
|Migration from any old dim_STAT version to the new one|
Migration procedure is quite easy:
- Stop all activity on your current dim_STAT installation
- Stop HTTPD and MySQL servers
- Backup all your databases from '/apps/mysql/data/' (see below) except: dim_00, mysql and dim
- mysql: system database, please, don't play with it :)
- dim_00: is a reference database and changing with every release
- dim: is a 'Default' database, and if you _really_ need it - rename it before backup!
- Install new dim_STAT distribution
- Restore your backuped data into '/apps/mysql/data'
- Start dim_STAT-Server
- Enjoy :))
NOTE: old database should be seen as before and work correctly, but if you want to get an advantage of the all new features coming within new version - create new database and start new collect(s).
Main point: ANY SECURE SYSTEM IS NEVER SECURE ENOUGH...
The question is only in what you'll consider ENOUGH for you :))
Any way, security point was so often involved during discussions with our engineers and customers than I cannot leave it without attention...
For paranoia-users: there is Linux version of dim_STAT, and if you really need maximum protection you can always spend money for small dedicated Linux PC, run dim_STAT on it and protect any access with firewalls, etc. etc.
On my experience, I may just suggest to protect Web server access in case if somebody just by error stop or suspend you some active collects. For this kind of first-level access protection good candidate should be Apache's ".htaccess". For more detailed information, please, refer to Apache documentation. But in few words, just to make it work for dim_STAT:
1.) via /apps/httpd/bin/htaccess create /apps/httpd/etc/.htpasswd file and add any pairs user/password you need
2.) create ".htaccess" file with context:AuthName "Welcome to dim_STAT Host" AuthType Basic AuthUserFile /apps/httpd/etc/.htpasswd require valid-user
3.) copy ".htaccess" file into /apps/httpd/home/docs and /apps/httpd/home/cgi-bin
4.) try to connect to your web server now and check access user/password - that's all! ;-)
Example:$ /apps/httpd/bin/htpasswd Usage: htpasswd [-c] passwordfile username The -c flag creates a new file. $ /apps/httpd/bin/htpasswd -c /apps/httpd/etc/.htpasswd login1 Password: ... $ vi /tmp/.htaccess $ cat /tmp/.htaccess AuthName "Welcome to dim_STAT Host" AuthType Basic AuthUserFile /apps/httpd/etc/.htpasswd require valid-user $ $ cp /tmp/.htaccess /apps/httpd/home/cgi-bin $ cp /tmp/.htaccess /apps/httpd/home/docs