 Port Guardian is a Linux GTK program with GUI to monitor the Firebird Database Server and databases, to check instantly if they are in operation Alive/Dead, Up/Down; and listen/monitor/record the in/out tcp packets on the set net IP and Port. The basic difference between Port Guardian and most other Net/Port monitoring software is that it is rather a Net/Port security guardian than a net/port traffic controller/ statistician. Port Guardian's major concern is not the bottleneck of the net traffic, but rather WWW -- who, when, what has been done on the concerned IP/Port, and will record it to a database to keep it as a history forever; though the packet is as brief as a shadow and gone even before fully shown (size-cut). And as a by-the-way function it can also set alive an instant alarm when user-set critical/sensitive word/phrase is found during the listening/monitoring/recording. Of course it won't set you on alarm, I hope. In the TO-DO list is kod (kiss-of-death) or tcpkill to terminate a dangerous tcp connection when a hi-alarm is triggered... Port Guardian has its own database packetsafe.fdb with one table in it: /* Table definition */ /* Table: PORTPACKET, Owner: SYSDBA */ CREATE TABLE PORTPACKET (RCDNO INTEGER NOT NULL, PCK_DATE DATE, PCK_TIME TIME, PCK_TMSTAMP TIMESTAMP NOT NULL, PCK_NAME VARCHAR(60) NOT NULL, PCK_LEVEL VARCHAR(14), PCK_TYPE VARCHAR(16), PCK_KEYWD VARCHAR(40), PCK_CONTENT BLOB SUB_TYPE 0 SEGMENT SIZE 80, PCK_REMKS BLOB SUB_TYPE 0 SEGMENT SIZE 80, PRIMARY KEY (RCDNO)); create generator gen_rcdno_id; set generator gen_rcdno_id to 0; CREATE TRIGGER TRG1_PORTPACKET FOR PORTPACKET ACTIVE BEFORE INSERT POSITION 0 AS BEGIN if (NEW.RCDNO is NULL) then NEW.RCDNO = GEN_ID (gen_rcdno_id, 1); END CREATE TRIGGER TRG1_PORTPACKET FOR PORTPACKET ACTIVE BEFORE INSERT POSITION 0 AS BEGIN if (NEW.RCDNO is NULL) or (NEW.RCDNO = 0) then NEW.RCDNO = GEN_ID (gen_rcdno_id, 1); END So you can see RCDNO is actually an auto-increment column. You have to be a root to run this program. Port Guardian performs two basic functions: /*************************************************************************************** * * * 1. Database Server and Databases monitoring/listening. * * * *****************************************************************************************/ It can monitor/check up to max. 100 databases simultaneously. It will mark the downed Server/database with red color in the listing, and trigger an alarm siren and a shell script according to user's setting. It will do the monitoring/checking automatically in every 30 seconds, 24x7, rain or shine. The scanning interval (in seconds) is configurable by users. THE FIRST THING you have to do after the installation is to edit/re-write the database parameter file of /roo/portguard.dat. It is a plain delimitated text file with the formation as following: hostname,database-name,user-name,user-password localhost,/home/myname/db-name.fdb,my-user-name,my-password hostname,/full/path/sub-dir/db-name.fdb,user-name, password localhost,/home/employee.fdb,sysdba,masterkey and so on... and so on... END,END,END IMPORTANT WITHOUT : after the hostname. NO white space within/between lines, particularly NOT before the comma for it will be taken as part of the name. this will be the 101th line) There is no need to install any third-party Firebird library/driver for Port Guardian is compiled with a built-in static library to communicate with Firebird Server. This is how it looks when Port Guardian is just started. On the right-top corner is the Server/Databases listing, now it is blank.  Server and Database Monitor Press the 'Start Monitoring' button below it, and wait a while ( the scanning interval) then you should see a listing like this:  Tip: you can create a fake/empty database and put it within the top 5 in the listing of the portguard.dat file. Then use the 'ShutDown Database' button (see below) to bring down this fake/empty database on purpose. It will be scanned as a downed database by Port Guardian and thus marked it by red, ( you can see it without scrolling the vertical bar as it is within the top six ), and trigger off the alarm siren if you have also set it; thus to prove Port Guardian is working properly. All the check-boxes below the listing are, from left to right: Down-Log This function will write a text log file each time Port Guardian detects a downed Server/database to register the time and name. The file is /usr/share/dbguard/db-down.log Down-Trigger This function, if set, will trigger the alarm siren as soon as Port Guardian has detected a Server/Database down. Port Guardian uses canberra-gtk-play for sound-playing, and you can replace the sound file of /usr/share/dbguard/sounds/db-down.wav with any other wav files, but with the same name. And at the same time it triggers a shell script in /usr/ share /dbguard/plugins/database-down.sh. You should edit/re-write it to do the job you want. a terminal. Monitoring-beat This function will sound three beats in every scan, and it is inspired by a true stroy in history. An exiled emperor ordered his servants to beat a wooden fish( a percussion idiophone like wood sound block) and shout at him regularly: "My fallen Majesty, have you forgotten the shame of how you lost the empire!" And he would answer: "No, not even for a blink of moment dare I do. Below the all-seeing heaven and upon the all-bearing earth, in front of my people and behind my ancestors, the humble accused dares not for a single moment forget the shame, but rather welcome all the bitter curses and bloody blame..." Of course the beatings here are nothing so serious at all, it is just reminding you: "My dear SYSDBA, have you forgotten your responsibility, but Port Guardian is standing sentry for you day and night." Buttons Save To File It will write the listing to a text file so that it can be recorded forever. ( useful if you want to prove/check the status of the Server/databases at a specific time past) Stop Monitoring This button will turn off the monitoring performance. You will have to wait a while (scan interval) before it returns. The default scan interval is 30 seconds, but you can re-set it to another duration according to your net/Server load. Start Monitoring Starts the monitoring and, if successful, hides itself after starting. This is how it looks when one database is down.  =============================================== Server/DB Services, right to the Server and Database Monitor buttons from top to bottom: Shutdown Firebird Database Server Now  When the Firebird Server is down, all databases are down. It makes all, and it mars all.  Shutdown Firebird Database Server in ... Minutes (can be dozens..hundreds..min)  Delayed Minutes Entry put in how many minute to delay before start/stop the Firebird Server. Start Firebird Database Server in ... Minutes Start Firebird Database Now Manually check Firebird Database Server now  Buttons below the editor, from left to right Database Status will show the status of the database in the left-side Database connection parameters. It will write the status text in the text editor which can be save to a file.  Force Sweep will immediately sweep the garbage of the above database ReadOnly will set the above database to this mode. ReadWrite set the above database to this mode. Sync-Write set the above database to this mode. ASync-Write set the above database to this mode. Clear Text will clear the text in the Test Editor. Save To File will save the Text Editor's content to a file. =========================================== SQL Command, right to the Server/DB Services Panel The main text editor is where users write SQL command. Check-boxes from top to bottom: switch screen After users have issued a SELECT SQL command by pressing the SQL SELECT button, the screen will automatically switch to data-grid. (treeview liststore) stay current It will not change the screen, but staying in the monitoring listing. blobsize 0 The SELECT command will omit all blobs in the results, treating them as null.  Above screeshot shows switch screen and blobsize 0. blobsize 1k The SELECT command will read each blob for 1024 bites only in the results.  compare the difference between blobsize 0 and blobsize 1k blobsize 3k The SELECT command will read each blob for 3x1024 bites only in the results. blobsize 5k The SELECT command will read each blob for 5x1024 bites only in the results. Buttons from top to bottom: SQL-SELECT It accepts only the select SQL, and will show the returned result in a data-grid. SQL DDL To execute a DDL SQL. DDL Script To execute a SQL DDL Script, each SQL command must end with ; ClearSQL Clear the SQL editor text. LoadSQL Load a SQL command as a text file. SaveSQL Save the SQL editor text to a text file. ================================================================ On the upper-left corner are tcp port listening and database connection parameters fill in the host-name, database name, user name and password accordingly. IMPORTANT !!! THERE IS WITHOUT : after the host name. Buttons Connect will try to connect this database. Dis-connect is to dis-connect it. Shutdown-DB will shut down this database. You can use this function to shut down the fake/empty database mentioned above. Bring-Back DB can bring back the shutdown database. All of the SQL functions described above depend on these parameters to act. But is is NOT necessarily to really connect the database just for the SQL functions, because the SQL function will connect to the database by itself separately. ( start a new process ) /*************************************************************************************** * * * 2. IP/Port listening/monitoring/recording function. * * * ***************************************************************************************/ Another major function of Port Guardian is to monitor/check/record packet traffic within or in/out of the localhost. It is highly recommended that Port Guardian is installed on the same machine with the Firebird Server. (behind firewall and any ciphering functions) Port Guardian uses tcpflow to capture the packets. (yum install tcpflow, or http://www.circlemud.org/jelson/software/tcpflow or http://sourceforge.net/projects/tcpflow If you make install, remember ./configure --prefix=/usr. Port Guardian expects tcpflow in /usr/bin, and will operate in /root) It will list and refresh the captured packets in every 3 seconds in a database DB grid. The default listening port is 3050 for Firebird Database Server: tcpflow -b 2048 -i lo -s port 3050. Port Guardian will response to all valid tcpflow commands, the only restriction is that there is a packet size limitation of max. up to 4096. ('-b 512 or 1024 or 2048(default) or 4096). Port Guardian has no way to predict how large a returned SQL result can be in a packet flow captured, and it will not wait nor store such a large data into its database--packetsafe.fdb, so it has to make a 'clear size-cut' to every packets. Of course you can change the tcpflow command, for example if you set it as: 'tcpflow -b 512 -i eth0 -s', you will listen to all tcp traffic in/out of ethereal interface 0 on you machine. And if you set it to port 1521 then you will put your ear on the gate to Oracle, hearing what these big boys are doing behind their closed doors. On the upper-left corner is: tcp port listening functions, from left to right: tcp command (max. -b 4096) This is the entry where you can give the tcpflow command, which must include either -b 512, or -b 1024, or -b 2048, or -b 4096 IP the concerned IP address you want to listen to. The default is 127.000 for lo=localhost Port Guardian will use this IP address to check the captured packets and pick them out from all others. Port Guardian will list a packet if the packet name includes the IP address like this (127.000.nnn.nnn), so you can set this IP address pin-pointed to one specific IP only such as 127.000.000.001. Port The Port number under your concern. The default is 3050, any packets in and out of this port will be captured and listed. Below it are four buttons, from left to right: listen This button will issue the tcpflow command you set above, and start at the same time the listing. The title of 'tcp command (max. -b 4096)' will change to PORT GUARDIAN IS LISTENING in red, as well as the buttons titles: listening and listing. stop-listen terminate the tcpflow by killing the tcpflow process list start listing of the captured packets in the liststore below. stop-list stop the above listing, you may have to wait a while for the thread to loop over. (the thread will not terminate immediately as it has to do some cleaning job) Below the Captured Port Packet Listing data grid are five check-boxes and three buttons: CheckBox with chime If checked, all four buttons in the database parameters will have a sound when pressed. /usr/share/dbguard/sounds/login.wav and logout.wav. record out-going Normally Port Guardian will not record any out-going packets into its database, though it will list them in the listing. If checked, the out-going packets will also be saved into the database. (max. 4096) record DB monitoring By default Port Guardian will not record any database alive/down monitoring packets into its database, though it will list them in the listing. If checked, these packets will also be saved into the database. no monitoring list Port Guardian will list all database alive/down monitoring packets by default; if checked, it won't list them any more, but list only all other in/out packets. sweep in every ... minutes Port Guardian will delete each packet after it is listed and saved into the database, thus it will be no packets left after each listing. But if you are running a heavily loaded server with very busy traffic, there may be some packets piling up for listing/deleting. If so, check this function alive to make a forced sweep of all packets in every set duration automatically. Adjust the scan interval and list interval to match to your system (read below in Alarm Level Setting) Three Buttons: Clear listing This button will clear all listings and sweep all packets in /roo, and trigger the stop-listen and stop-list functions. After it is pressed you have to re-start the listening and listing again. tcpflow default To set the tcp command, IP, and Port entries to its default value; tcpflow -b 2048 -i lo -s port 3050, 127.000, 3050 list latest 100 This is actually a SQL function to retrieve the latest 100 records from the table of portpacket in the database of packetsafe.fdb, and show them in the Guardian's Data Grid. (the min. records to retrieve is 100 records)  =============================================================== Guardian's Data Grid (above screenshot) This is the default data-grid for the portpacket table to show the captured packets. When retrieving the records and have them shown here, the data-grid will show them in different colors according to their PCK_LEVEL, PCK_TYPE, and PCK_KEYWD. The row will be red if the PCK_LEVEL is High, green if PCK_TYPE is in-coming and connect, blue if PCK_KEYWD is a DDL, yellow if it is out-going. (see above screenshot) Under the data-grid on the left-side is a text editor. The content of PCK_CONTENT will be taken/shown here when user double-clicks on the selected row.  Right to it is the SQL editor where user can enter SQL command like: select * from portpacket where RCDNO > 1000 or any other standard/valid SELECT SQL's. Any SQL from this editor is effective ONLY to the packetsafe.fdb, and no need to get connected to for it is connected. ( it does not support select ....return) Buttons on the bottom from left to right: restore packets to files This button will restore all listed rows back to its original packet form as when they were captured, each with its same original packet names like : 127.000.000.001.03050-...... All restored packet files will be in /usr/share/dbguard/packets/ * first step. SELECT from the table, get rows listed in the data-grid. * second step. press this button to get all rows restored in /usr/share/dbguard/packets/.  clear content text Clear text in the above text editor. save content to file Save the showing text content to a text file. clean SQL text Cleans the text in SQL editor. Load SQL from file Load a SQL text command file into the SQL editor Save SQL to file Save the text in SQL editor to a text file. execute SELECT SQL does what as the title says. ======================================================================= SQL Result Data Grid This is the default Data Grid for SQL Command function described above. All the buttons below it from left to right: TextReport This button will make a text report from the data grid listings (all rows, including blob content): first step. SELECT from the table, get rows listed in the data-grid.  second step. press this button to get the text report in the Main Text Editor.  Text Report for select * from job AboutBox after press the About button, otherwise test report only. ------------------------------------------ Under the text editor ( now showing the text report ) are three buttons: Clear Text clear the text editor's text. LoadFileToEditor load a plain text file to the editor Save Text To File save the editor's text to a plain text file. On the left are AboutBox and the on-line-help button. see above screenshot ---------------------------------------------- RemoveSelected This button removes/delete the selected/hi-lighted row from the listing. ClearList clear all listings, making a blank liststore. LoadFromFile load a save text file (see below) into the data-grid. SaveToFile save the listed rows into a text file (including the blob content). =================================================================== Alarm Level Settings IMPORTANT All settings have to be done ( take effective) BEFORE the starting of listing, NOT after NOR during the listing!  There are three text entry editors here, separately for Low Level Keywords Middle Level Keywords High level Keywords enter the words list you want Port Guardian to look for in the in-coming and out-going packets. ( each packet size 512 ~ 4096 ) It is in delimit formation, end each words/phrase with a comma, and leaving no white space: FIRST_WORDS, SECOND_PHRASE, ANOTHER_WORDS, AND_SO_ON, It can be an completely empty list, as the default. The Low Level and Middle Level words will not trigger any alarm, nor change any color. But the High Alarm will trigger an alarm/shell script and change color, if user has set for it. There is no limits on how many words/phrases you can set, but a warning I would like to repeat here: "Long list means longer time of processing, losing focus, and controlled by what should be controlled" The three radio choices are separately for the three common buttons below LoadKeyWords load the saved key-word text file into the radio-button-selected editor SaveKeyWords save the text in the text editor selected by the radio button to a text file. ClearText clear the text in the text editor selected by the radio button to a text file. High Alarm Siren check-box If checked, a siren will be sounded when Port Guardian detects a High Alarm words/ phrase /usr/share/dbguard/sounds/hi-alarm.wav High Alarm Trigger check-box If checked, the shell script will be triggered when Port Guardian detects a High Alarm words/phrase. You have to edit/re-write it to do the job you want. Run Port Guardian ( ./dbguard ) in a terminal you can see what it is doing now. Listing Interval... Seconds check box if checked, set the listing interval ( pause duration between each listing loop ). the default interval is 3 seconds Scan Interval... Seconds check box if checked, set the scanning interval ( pause duration between each scan loop for databases up/down ). The above two check boxes ( together with the sweep interval, if necessary )may be the place where a SYSDBA has to show his/her capability/understanding over the whole system under control. Changing/setting these intervals can manage/control the traffic load among all client connections and databases monitoring. It is in the motion, changing, moving, pausing, over-whelming and balancing that your talent, power, skill and grace will have a full play. Tips: If you, together with the system under load, are more than equal to do the above job, try to run sniffit together with tcpflow, and see what else you can capture. ==================================================================== Conclusion: Two Basic Functions: 1. monitoring the Server and databases 2. listen to the Port, capture tcp packets and save them into a database. Some Supporting Functions SQL functions Alarm functions Text (report) functions Totally three Data-Grid (liststore view) Three Text Editors (database status, ISQL editor, main Editor) Port Guardian is only an interface between user and Firebird Server/tcpflow, which Port Guardian depends on for all its performances .... (both are open source free software, you can get them at http://sourceforge.net) Now let's put Port Guardian onto the stage to float the flow: mock the world with a flashy show, though the acting face must hide what the actor's heart does know! Download: rpm package with dbguard executive only download-dbguard Your comments, suggestions, testing, using, and bug-reporting are very much appreciated. Author: Taoman Li <daomannlee@gmail.com> |