========== IMPORTANT NOTE =============== Access via the php-script is still experimental, and does not work in a generic environment. In addition, it may pose serious security problems. Do not use it, unless for development purposes. You use the rest at your own risk, as usual. ========================================= INSTALLATION ============ Download the tgz file from http://www.di.unipi.it/~augusto. When you unpack the code using "tar -xzf", a new directory is created, containing several sub-directories: Producer: the directory containing producer's scripts; Consumer: the directory containing consumer's scripts; jameter-php: the directory containing the scripts for a variant of the above Consumer with a WWW interface; SQLregistry: the directory containing consumer's scripts; lib: libraries (it should not be necessary you go in there). Your first option is whether you want to install the code in your home directory or in any directory where you can write (root password is not required) or to make a system installation (root password is required) or to arrange so that the processes start on their own at boot. In any case, if your SQL database is not yet prepared, you have to go into the "SQLserver" directory and prepare the directory: this step must be executed only once, calling the "create.sh" script. Installing in your home directory ================================= Move into the jameter directory created in the previous step and decide what role your process will play: Consumer, Producer or SQLregistry. Then move into the appropriate directory. Here you can call the perl script that implements the role, or run the script that creates the database. To have a php access page running in this mode you should link the jameter-php/index.html file into your home page. Installing in system directories ================================ You have to decide which functionality to install on your host: move into the directory of interest and read the README. You can install any assortment of roles on a single host. Now any user should be able to invoke the installed commands, and the php access page should be accessibile using the local HTTP server. Automatic start at boot ======================= This is valid for debian distributions, and other distributions with similar boot organizations. - Unpack the tarfile in an appropriate place (/opt or similar). - Move the "jameter" file into the /etc/init.d directory - Create appropriate links to the jameter file in the /etc/rc*.d directories. For instance: # cp jameter /etc/init.d # ln -s /etc/init.d/jameter /etc/rc0.d/K15jameter # ln -s /etc/init.d/jameter /etc/rc1.d/K15jameter # ln -s /etc/init.d/jameter /etc/rc6.d/K15jameter # ln -s /etc/init.d/jameter /etc/rc2.d/S99jameter # ln -s /etc/init.d/jameter /etc/rc3.d/S99jameter # ln -s /etc/init.d/jameter /etc/rc4.d/S99jameter # ln -s /etc/init.d/jameter /etc/rc5.d/S99jameter To enable automatic start you have to create two files in the /etc/jameter directory - an empty /etc/jameter/target.conf file enables automatic start of the target. If the file is not there, the target is not started. - a /etc/jameter/probe.conf file enables automatic start of the sessions: each line in this file contains the basename of a session configuration file. These files are located in the "session" directory in the Producer directory. If the probe.conf file is not there, the target is not started. This approach is adequate for the target but is not completely satisfactory for the sessions: the script cannot be used to restart terminated sessions, since it produces replicated sessions. It is safer to stop target and sessions calling the script with "stop", and restart everything with "start". ============ Documentation in Italian (English version soon coming) ======== Descrizione =========== Serve a monitorare un path, acquisendo informazioni sul jitter unidirezionale senza sincronizzare i clock. Funziona come un ping, con un nodo (probe) che spedisce pacchetti ai quali l'altro (target) risponde. Il programma di misura, session.pl, spedisce pacchetti ad un solo nodo target, specificando l'intervallo tra i ping (periodo), la lunghezza del pacchetto, e la porta sulla quale vuole ricevere le risposte. Su un nodo possono girare più programmi di probe, ma ciascuno deve specificare una porta di ricezione diversa. Il programma session.pl può produrre in uscita un file di log in cui registra le informazioni rilevanti su ciascun ping, oppure pubblicarle in un database SQL. Il programma di target, target.pl, riceve pacchetti da qualunque nodo, e a questo rispedisce la risposta. Quindi uno stesso programma target può servire a più probe su nodi diversi. Usa in ingresso la porta 22000, configurata nel programma. Istruzioni per l'installazione e l'esecuzione ============================================= Spacchettare il file jameter.tgz in /tmp, ed invocare come root lo script "install.sh". Verificare prima che le directory di installazione corrispondano a quelle in uso nel sistema ospite. -> sul target: - Avviare il demone target.pl $ ./target.pl > /dev/null & Se server l'output può essere ridiretto su un file di log. -> sul probe: - Avviare il programma session.pl fornendo come parametro il nome di un file di configurazione. Il contenuto del file deve rispettare una semplice sintassi, e deve specificare -tutti- i parametri seguenti (al momento, nessuno è opzionale): probeIP Indirizzo del probe (IP o mnemonico). targetIP Indirizzo del target (come sopra). port Porta di ricezione sul probe. (indicato 22001) period Periodo di campionamento (secondi, in virgola mobile) (indicato 5). length Lunghezza del pacchetto (in ottetti) (max 1024). scale Fattore di scala dei tempi ([0..15], indicato 10). version La versione (0) Andrà modificato... Opzionalmente possono essere inseriti i parametri relativi al server SQL: la loro presenza condiziona il probe a pubblicare i risultati sul database SQL, e non sullo stdout. SQLserver hostname del server SQL SQLuser nome dell'utente che accede al database SQLdatabase database contenente i dati SQLpassword password dell'utente per accedere al database La sintassi: il file è composto da tante righe quanti sono i parametri: ciascuna riga è composta dal nome del parametro (riportato a sinistra nella tabellina sopra) e nel valore da associare al campo. Le due stringhe sono separate da un singolo tab. Il parser in questo momento non tollera eccezioni: niente spazi superflui o righe vuote. Sul server SQL ============== Il server deve essere preparato con utente, database e password da comunicare ai probe e ai consumer. Tutti i dati di tutti i probe vengono memorizzati in due tabelle: - NetworkVerbosePing mysql> describe NetworkVerbosePing; +------------+-----------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +------------+-----------------+------+-----+---------+-------+ | nmidSource | varchar(64) | YES | | NULL | | | nmidTarget | varchar(64) | YES | | NULL | | | tool | varchar(10) | YES | | NULL | | | version | double(4,2) | YES | | NULL | | | port | int(5) unsigned | YES | | NULL | | | period | double(8,2) | YES | | NULL | | | packetsize | int(4) unsigned | YES | | NULL | | | scale | int(2) unsigned | YES | | NULL | | | identifier | int(5) unsigned | YES | | NULL | | +------------+-----------------+------+-----+---------+-------+ descrive un singolo run del probe. L'identificatore è in indice che identificherà i dati provenienti da un certo run, nella tabella successiva. - NetworkVerbosePingData mysql> describe NetworkVerbosePingData; +------------+-----------------+------+-----+---------------------+-------+ | Field | Type | Null | Key | Default | Extra | +------------+-----------------+------+-----+---------------------+-------+ | identifier | int(5) unsigned | YES | MUL | NULL | | | timestamp | datetime | | PRI | 0000-00-00 00:00:00 | | | sendFwd | float(7,5) | YES | | NULL | | | diffFwd | float(7,5) | YES | | NULL | | | pmdFwd | tinyint(1) | YES | MUL | NULL | | | diffLat | float(7,5) | YES | | NULL | | | diffBwd | float(7,5) | YES | | NULL | | | pmdBwd | tinyint(1) | YES | MUL | NULL | | +------------+-----------------+------+-----+---------------------+-------+ l'identificatore "identifier" è utilizzato per associare la riga al run del probe. Il "timestamp" specifica la data completa al secondo. I campi successivi sono timestamp scalati (sendFwd, diffFwd, diffLat e diffBwd), e gli indicatori di minimo potenziale. Per questi non ho potuto utilizzare il tipo (economico) char(0) perchè non consente indici. Per la descrizione dei singoli campi vedi la descrizione del file di log. Interpretazione dei risultati nel file di log ============================================= L'uscita del programma 'session.pl' viene riversata sullo stdout, e si articola in una serie di righe deliberatamente compatte e non user friendly. Le prime righe sono così codificate, sulla base del carattere del carattere iniziale della riga: V - riporta la versione P - riporta i parametri proposti dal probe T - Riporta i parametri controproposti dal target . - conclude la prima parte Le righe successive riportano risultati rilevanti: iniziano con '<', quelle che riportano errori o situazioni eccezionali con '!', i messaggi persi vengono invece segnalati con un ?. Ogni riga riporta, nell'ordine: - l'istante di conclusione del roundtrip (in secondi alla maniera di Unix), - il timestamp corrispondente alla spedizione del messaggio forward, - la differenza tra i timestamp di spedizione e ricezione del messaggio forward; - la differenza tra il timestamp del messaggio di ricezione del messaggio forward, e la spedizione del messaggio backward; - la differenza tra i timestamp di spedizione e ricezione del messaggio backward. Per i messaggi persi viene indicato solo l'istante in cui è stata rilevata la perdita del messaggio. I timestamp sono tutti riferiti al clock locale del nodo su cui si verifica l'evento, quindi risentono della non sincronizzazione dei clock. Al file di log possono essere aggiunte altre righe che cominciano con #, e che possono essere utilizzate per inserire intestazioni o commenti. //////////////////////////////////////// Tool per l'analisi del log ===================================================== Il tool di analisi principale è il programma 'probe.pl'. Prende dallo standard input il log generato dal programma './session.pl' e lo analizza. All'inizio della sessione vengono riportati i dati con cui è stato invocato probe.pl: ============== Session header ============== VERSION 0 Probe: accapi Target: casalin Port on probe: 22400 Round period: 1.10 seconds Packet length : 1000 bytes Timestamp scale: 10 == Session opening successful! Quindi vengono riportati i dati negoziati dal target (che può modificare le richieste del probe): Round period: 1.10 seconds Packet length : 1000 bytes Timestamp scale: 10 == 2 rounds needed to warm up Ciascun round successivo al terzo genera sullo stdout un blocco di dati di questo tipo: ================== At Thu Jun 6 15:45:10 2002 Timestamp: 1894.470585 Jitter asymmetry: 13.35 raw delta delta jitter a b Forward 3534.3553 0.001175 0.000059 3534.8046 -2.371e-04 Backward 561.6484 0.000063 0.000003 561.5761 3.816e-05 ================== La prima riga informa sull'istante in cui è stato eseguito il ping. La seconda è un timestamp progressivo con la precisione del microsecondo. La terza riga è il jitter asymmetry. Le righe Forward e Backward sono relative ai due percorsi. La colonna più significativa è quella intestata "jitter", che da' il jitter stimato unidirezionale. Quando il jitter è basso, le ultime due colonne danno rispettivamente una stima dell'offset relativo ed del drift relativo dei due clock: per offset piccoli (non come nel caso di sopra) dovrebbero essere una opposta all'altra, in segno, almeno approssimativamente. Ad es.: $ ./probe.pl < prova.log | less oppure anche $ ./session.pl pippo pluto 22400 1.5 1000 10 | ./probe.pl E' sempre consigliabile tuttavia usare un file di appoggio per il log, in modo da poterlo rielaborare successivamente. Tool di visualizzazione ======================= I programmi "plot_.pl" visualizzano la metrica indicata dal nome stesso. Prendono sempre in ingresso il risultato del programa ".\probe" (DAFARE meglio prendere in ingresso direttamente il log). Nel file /tmp/plot.dat c'è il risultato del filtraggio dei dati utilizzati per la visualizzazione. Le prime colonne riportano la data, le successive i dati. Ad es.: $ ./probe.pl < prova.log | ./plot_jitter_asymmetry.pl