{"id":19390857,"url":"https://github.com/tecnickcom/serverusage","last_synced_at":"2025-10-07T10:38:37.694Z","repository":{"id":27719252,"uuid":"31206505","full_name":"tecnickcom/ServerUsage","owner":"tecnickcom","description":"The ServerUsage system is designed to collect and process statistic information from computers running a GNU-Linux Operating System.","archived":false,"fork":false,"pushed_at":"2020-02-01T10:47:26.000Z","size":185,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-07T09:46:09.560Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tecnickcom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.TXT","contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"custom":["https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026currency_code=GBP\u0026business=paypal@tecnick.com\u0026item_name=donation%20for%20serverusage%20project"]}},"created_at":"2015-02-23T12:06:57.000Z","updated_at":"2023-07-05T08:51:18.000Z","dependencies_parsed_at":"2022-09-02T23:20:12.438Z","dependency_job_id":null,"html_url":"https://github.com/tecnickcom/ServerUsage","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecnickcom%2FServerUsage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecnickcom%2FServerUsage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecnickcom%2FServerUsage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecnickcom%2FServerUsage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tecnickcom","download_url":"https://codeload.github.com/tecnickcom/ServerUsage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240557495,"owners_count":19820359,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T10:23:36.145Z","updated_at":"2025-10-07T10:38:32.651Z","avatar_url":"https://github.com/tecnickcom.png","language":"C","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026currency_code=GBP\u0026business=paypal@tecnick.com\u0026item_name=donation%20for%20serverusage%20project"],"categories":[],"sub_categories":[],"readme":"ServerUsage - README\n====================\n\n+ Name: ServerUsage\n\n+ Version: 6.3.8\n\n+ Release date: 2012-11-29\n\n+ Author: Nicola Asuni\n\n+ Copyright (2012-2012):\n\n\u003e \u003e Fubra Limited  \n\u003e \u003e Manor Coach House  \n\u003e \u003e Church Hill  \n\u003e \u003e Aldershot  \n\u003e \u003e Hampshire  \n\u003e \u003e GU12 4RQ  \n\u003e \u003e \u003chttp://www.fubra.com\u003e  \n\u003e \u003e \u003csupport@fubra.com\u003e  \n\n\nSOFTWARE LICENSE:\n-----------------\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License along with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\nSee LICENSE.TXT file for more information.\n\n\nDESCRIPTION:\n------------\n\nThe ServerUsage system is designed to collect and process statistic information from computers running a GNU-Linux Operating System.\n\nThis project is composed by:\n\n\n## ServerUsage-Server ##\n\nThe ServerUsage-Server program listen on a TCP port for incoming log data (from ServerUsage-Client) and store them on a SQLite table. An script (serverusage_dbagg.sh) is executed periodically to aggregate data on another table and delete obsolete data.\n\nThe serverusage_api.php script can be remotely used to extract formatted data from the database or display graphs.\n\n\n## ServerUsage-Client ##\n\nThe ServerUsage-Client program is composed by two main sections: the SystemTap (http://sourceware.org/systemtap) serverusage_client.ko kernel module to collect and output usage statistics of the machine where it is installed, and the serverusage_tcpsender.bin to send the output to a log server via TCP.\n\n\n## ServerUsage-Client-MDB ##\n\nThe ServerUsage-Client-MDB program is used to collect user statistics form a MariaDB database.\n\n\n\n## GENERAL USAGE SCHEMA ##\n\t\n\t(ServerUsage-Client) - - TCP CONNECTION - -\u003e (ServerUsage-Server)\n\n\t([serverusage_client.ko]==\u003e[serverusage_tcpsender.bin]) - - TCP CONNECTION - -\u003e ([serverusage_tcpreceiver]==\u003e[SQLite log_raw table (raw data)])\n\n\t[SQLite log_raw table]==\u003e[serverusage_dbagg.sh]==\u003e[SQLite log_agg_hst table (aggregated data)]\n\n\t[SQLite log_agg_hst table]==\u003e[serverusage_api.php]==\u003e[Data with selected format or SVG graph]\n\n## API ##\n\nThe serverusage_api.php script can be remotely used to extract formatted data from the database or display graphs.\n\n### PARAMETERS: ###\n\n\tfrom: (integer) starting timestamp in seconds since EPOCH;\n\tto: (integer) starting timestamp in seconds since EPOCH - this value can be at maximum equal to (current_time - (2 * DB_AGGREGATION_DELAY)) that is also the default value;\n\tmetric: (not available with svg mode) type of info to extract; Possible values are: 'uid', 'ip', 'uip', 'grp', 'glb', 'all'. The return values for each metric are:\n\t\tuid : user_id, cpu_ticks;\n\t\tuidt : user_id, cpu_ticks, minimum start time, maximum end time;\n\t\tip  : ip, net_in, net_out;\n\t\tipt  : ip, net_in, net_out, minimum start time, maximum end time;\n\t\tuip : user_id, ip, cpu_ticks, io_read, io_write, net_in, net_out;\n\t\tuipt : user_id, ip, cpu_ticks, io_read, io_write, net_in, net_out, minimum start time, maximum end time;\n\t\tgrp : start_time, end_time, user_id, ip, cpu_ticks, io_read, io_write, net_in, net_out;\n\t\tglb : (default for SVG mode) lah_start_time, lah_end_time, lah_cpu_ticks, lah_io_read, lah_io_write, lah_netin, lah_netout;\n\t\tall : start_time, end_time, process, user_id, ip, cpu_ticks, io_read, io_write, net_in, net_out.\n\tuid : (integer) if set, filter result for the requested user ID;\n\tip : (IP address) if set, filter result for the requested IP address.\n\tmode: output format ('json' = JSON, 'csv' = CSV TAB-Separated Values, 'psa' = base64 encoded PHP Serialized array, 'svg' = SVG).\n\n\tADDITIONAL PARAMETERS FOR SVG MODE:\n\n\twidth: (integer) optional width for SVG output (default 1024; minimum 50).\n\theight: (integer) optional height for SVG output; will be rounded to a multiple of 5 (default 750, minimum 50).\n\tscale: linear = vertical linear scale (default), log = vertical logarithmic scale.\n\tbgcol: type of background color: 'dark' or 'light' (default). Note: the SVG background is always transparent.\n\tgtype: sequence of number representing the graphs to display: 1 = CPU TICKS, 2 = IO READ, 3 = IO WRITE, 4 = NET IN, 5 = NET OUT. Default: 12345.\n\n### USAGE EXAMPLES: ###\n\n\tJSON:\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=uid\u0026mode=json\n\t\tserverusage_api.php?from=1332769800\u0026metric=uidt\u0026mode=json\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=ip\u0026mode=json\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=ipt\u0026mode=json\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=uip\u0026mode=json\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=uipt\u0026mode=json\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=all\u0026mode=json\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=all\u0026uid=320\u0026mode=json\n\n\tCSV:\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=all\u0026uid=320\u0026mode=csv\n\n\tBASE64 ENCODED PHP SERIALIZED ARRAY:\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026metric=all\u0026uid=320\u0026mode=psa\n\n\tSVG:\n\t\tserverusage_api.php?from=1332769800\u0026to=1332845100\u0026mode=svg\u0026width=1024\u0026height=750\u0026scale=log\n\t\tserverusage_api.php?from=1333532663\u0026to=1333627917\u0026mode=svg\u0026scale=log\u0026bgcol=light\u0026gtype=12345\n\t\tserverusage_api.php?from=1333532663\u0026to=1333627917\u0026mode=svg\u0026scale=linear\u0026bgcol=light\u0026gtype=15\n\t\tserverusage_api.php?from=1333532663\u0026to=1333627917\u0026mode=svg\u0026scale=log\u0026bgcol=light\u0026gtype=5\n\n### OUTPUT: ###\n\n\tThe output format can be JSON (JavaScript Object Notation), CSV (tab-separated text values), Base64 encoded serialized array or SVG (Scalable Vector Graphics).\n\n### ADDITIONAL NOTES: ###\n\n\tThe reference time for all servers should be the standard UTC.\n\tThe latest available time on the ServerUsage-Server aggregated table is always in the past by the value specified by DB_AGGREGATION_DELAY constant (by default 5 minutes).\n\tA valid time interval, for example, can be calculated as follows:\n\n\t\tpolling_interval = 900; // 15 minutes * 60 seconds; must be equal or greater than DB_AGGREGATION_DELAY.\n\t\tdelay_time = 600; // 10 minutes * 60 seconds; must be equal or greater than (2 * DB_AGGREGATION_DELAY).\n\t\tend_time = (current_time - delay_time);\n\t\tstart_time = (end_time - polling_interval);\n\nHOW-TO CREATE ServerUsage RPMs\n------------------------------\n\nThis is a short hands-on tutorial on creating RPM files for the ServerUsage project.\nFor an automatic building script for CentOS and the latest RPM packages please check the CatN Repository: https://github.com/fubralimited/CatN-Repo\n\nNOTE: The sever configuration for ServerUsage-Client and ServerUsage-Server may be different, so this process must be executed in different environments.\n\n## DEVELOPMENT ENVIRONMENT ##\n\nTo build RPMs we need a set of development tools.\nThis is a one-time-only setup, installed by running those commands from a system administration (root) account.\nNOTE: You may need to change the the \n\t\nInstall the EPEL repository:\n\n\t# rpm -Uvh http://download.fedoraproject.org/pub/epel/6/$(uname -m)/epel-release-6-7.noarch.rpm\n\nInstall development tools and Fedora packager:\n\n\t# yum install @development-tools\n\t# yum install fedora-packager\n\nThe following packages are required to create ServerUsage RPMs:\n\n\t# yum install kernel-devel elfutils-devel sqlite-devel.x86_64 sqlite.x86_64 MariaDB-devel\n\nInstall debug packages (change repository if you are not using CentOS):\n\n\twget http://debuginfo.centos.org/6/$(uname -m)/kernel-debug-debuginfo-$(uname -r).rpm\n\twget http://debuginfo.centos.org/6/$(uname -m)/kernel-debuginfo-$(uname -r).rpm\n\twget http://debuginfo.centos.org/6/$(uname -m)/kernel-debuginfo-common-$(uname -m)-$(uname -r).rpm\n\trpm -U --force kernel-debug-debuginfo-$(uname -r).rpm kernel-debuginfo-$(uname -r).rpm kernel-debuginfo-common-$(uname -m)-$(uname -r).rpm\n\nInstall SystemTap:\n\n\t# yum -y install systemtap systemtap-client systemtap-devel systemtap-runtime systemtap-initscript systemtap-grapher systemtap-sdt-devel systemtap-server systemtap-testsuite\n\nCreate a dummy user specifically for creating RPM packages:\n\n\t# /usr/sbin/useradd makerpm\n\t# passwd makerpm\n\nReboot the machine, log as makerpm user and create the required directory structure in your home directory by executing: \n\n\t$ rpmdev-setuptree\n\nThe rpmdev-setuptree program will create the ~/rpmbuild directory and a set of subdirectories (e.g. SPECS and BUILD), which you will use for creating your packages. The ~/.rpmmacros file is also created, which can be used for setting various options. \n\n\n## CREATE THE ServerUsage RPMs ##\n\nDownload the ServerUsage sources:\n\n\t$ cd ~\n\t$ git clone git://github.com/fubralimited/ServerUsage.git\n\nCopy the SPEC files and source files to rpmbuild dir:\n\t\n\t$ cd ~/ServerUsage\n\t$ export SUVER=$(cat VERSION) \n\t\n\t$ cd ~/ServerUsage/server\n\t$ cp serverusage_server.spec ~/rpmbuild/SPECS/\n\t$ tar -zcvf ~/rpmbuild/SOURCES/serverusage_server-$SUVER.tar.gz  *  \n\t\n\t$ cd ~/ServerUsage/client\n\t$ cp serverusage_client.spec ~/rpmbuild/SPECS/\n\t$ tar -zcvf ~/rpmbuild/SOURCES/serverusage_client-$SUVER.tar.gz  *  \n\t\n\t$ cd ~/ServerUsage/client_mdb\n\t$ cp serverusage_client_mdb.spec ~/rpmbuild/SPECS/\n\t$ tar -zcvf ~/rpmbuild/SOURCES/serverusage_client_mdb-$SUVER.tar.gz  *    \n\nCreate the RPMs:\n\n\t$ cd ~/rpmbuild/SPECS/\n\t$ rpmbuild -ba serverusage_server.spec  \n\t$ rpmbuild -ba serverusage_client.spec  \n\t$ rpmbuild -ba serverusage_client_mdb.spec  \n\n\nThe RPMs are now located at ~/rpmbuild/RPMS/$(uname -m)\n\n\nInstall ServerUsage-Server\n--------------------------\n\nThe ServerUsage-Server RPM must be installed only on the Log Server (the computer receiving the logs from the clients).\n\nAs root install the ServerUsage-Server RPM file:\n\n\t# rpm -i serverusage_server-6.3.8-1.el6.$(uname -m).rpm\n\t\nOnce the RPM is installed you can configure the ServerUsage-Server editing the following file:\n\n\t# nano /etc/serverusage_server.conf\n\nThe ServerUsage-Server includes a SysV init script to start/stop/restart the service:\n\n\t# /etc/init.d/serverusage_server start|stop|status|restart|reload|condrestart\n\nThe init script starts the serverusage_tcpreceiver.bin program that listen for incoming TCP connections from the clients, and install a cron job to aggregate the data every 5 minutes.\nThe raw data received from serverusage_tcpreceiver.bin is stored on a SQLite 3 database (var/lib/serverusage/serverusage.db) table named log_raw. The table containing the aggregated data is called log_agg_hst. The aggregated data is immediately removed from the log_raw table. The data on log_agg_hst older than DB_GARBAGE_TIME seconds is automatically removed.\n\nTo start the service at boot you can use the following command:\n\n\t# chkconfig serverusage_server on\n\nTo extract formatted information from the SQLite database you can use the serverusage_api.php. This file is installed by default in \u003cem\u003e/var/www/serverusage\u003c/em\u003e directory, so you have to configure Apache/PHP accordingly or move the script to another position.\nThe serverusage_api.php allows you to extract filtered information in various formats: JSON (JavaScript Object Notation), CSV (tab-separated text values), Base64 encoded serialized array or SVG (Scalable Vector Graphics). On the same directory where the file serverusage_api.php is, you can find an example HTML file that displays an auto-update graph using the php API.\n\n\nInstall ServerUsage-Client\n--------------------------\n\nThe ServerUsage-Client RPM must be installed on each client computer to monitor.\n\nAs root install the SystemTap-Runtime and ServerUsage-Client RPM files:\n\n\t# yum -y install systemtap-runtime\n\t# rpm -i serverusage_client-6.3.8-1.el6.$(uname -m).rpm\n\nConfigure the ServerUsage-Client\n\n\t# nano /etc/serverusage_client.conf \n\nSet the IP address of the Log server where ServerUsage-Server is installed and be sure that the specified TCP port is open on both client and server.\n\nThe ServerUsage-Client includes a SysV init script to start/stop/restart the service:\n\n\t# /etc/init.d/serverusage_client start|stop|status|restart|reload|condrestart\n\nWhen the service is started, the serverusage_client.ko SystemTap kernel module is executed via the staprun command and the output is piped to the serverusage_tcpsender.bin to be sent to the Log server via a TCP connection. If the connection is broken or the Log server is not responding, the log files are temporarily stored on \u003cem\u003e/var/log/serverusage_cache.log\u003c/em\u003e file and resent as soon the TCP connection is restored.\n\nTo start the service at boot you can use the following command:\n\n\t# chkconfig serverusage_client on\n\n\nInstall ServerUsage-Client-MDB\n------------------------------\n\nThe ServerUsage-Client RPM must be installed on the computer containing the MariaDB database.\n\nAs root install the ServerUsage-Client RPM file:\n\n\t# rpm -i serverusage_client_mdb-6.3.8-1.el6.$(uname -m).rpm\n\nConfigure the ServerUsage-Client\n\n\t# nano /etc/serverusage_client_mdb.conf \n\nSet the IP address of the Log server where ServerUsage-Server is installed and be sure that the specified TCP port is open on both client and server.\n\nThe ServerUsage-Client includes a SysV init script to start/stop/restart the service:\n\n\t# /etc/init.d/serverusage_client_mdb start|stop|status|restart|reload|condrestart\n\nTo start the service at boot you can use the following command:\n\n\t# chkconfig serverusage_client_mdb on\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftecnickcom%2Fserverusage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftecnickcom%2Fserverusage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftecnickcom%2Fserverusage/lists"}