                         ----------------------
                            Tuptime    Manual
                         ----------------------
                             version 3.2.10
                                Ricardo F.
                             13/November/2015



============
| Abstract |
============

Tuptime report historical and statistical running time of the system, keeping it between restarts.
Indeed, it can:

  - Count system startups
  - Register first boot time (a.k.a. installation time)
  - Count nicely and accidentally shutdowns 
  - Uptime and downtime percentage since first boot time
  - Accumulated system uptime, downtime and total
  - Largest, shortest and average uptime and downtime
  - Current uptime
  - Print formatted table or list with most of the previous values
  - Register used kernels



=================
| Prerequisites |
=================

Operating system:
   - Linux
   - FreeBSD
   - OSX (Darwin)

Software:
   - Python 2.7 or Python 3.X (Latest recomended)
   - Python modules (most included in python core by default):
       sys, os, optparse, sqlite3, datetime, locale, platform, subprocess, time

If a distro is used, all is met with:
    - In Linux:  'python' package >= 2.7
    - In FreeBSD: '/usr/ports/lang/python' and '/usr/ports/databases/py-sqlite3'
    - In OSX: 'python' installed by default in base system



================
| Installation |
================

For Linux systems:

   + Using .deb package

      If is a system based on .deb package, install tuptime_x.deb located
      in this repo under tuptime/deb-package/
      Note that systemd is required.

   + Using .rpm package

      If is a system based on .rpm package, install tuptime-x.rpm located
      in this repo under tuptime/rpm-package/
      Note that systemd is required.

   + Using .sh script:
      
      Download and execute the installation script:

         # bash <(curl -s https://raw.githubusercontent.com/rfrail3/tuptime/master/tuptime-install.sh)

   + Manual install

      Clone repository and copy executable file:

         # cp tuptime/latest/tuptime /usr/bin/tuptime
         # chmod 755 /usr/bin/tuptime 

      Copy cron file:

         # cp tuptime/latest/cron.d/tuptime /etc/cron.d/tuptime
         # chmod 644 /etc/cron.d/tuptime

      If is a system with systemd, copy service file and enable it:
	
         # cp tuptime/latest/systemd/tuptime.service /lib/systemd/system/
         # chmod 644 /lib/systemd/system/tuptime.service
         # systemctl enable tuptime.service

      If have upstart system, copy the file:

         # cp tuptime/latest/init.d/tuptime.init.d-redhat6 /etc/init.d/tuptime
	 # chmod 755 /etc/init.d/tuptime
	 # chkconfig --add tuptime
	 # chkconfig tuptime on

      If have init system, copy the file:

         # cp tuptime/latest/init.d/tuptime.init.d-debian7 /etc/init.d/tuptime
         # chmod 755 /etc/init.d/tuptime
         # update-rc.d tuptime defaults
	 # /etc/init.d/tuptime start


For FreeBSD system:

   * Using FreeBSD ports

     Located at /usr/ports/sysutils/tuptime

   * Using FreeBSD alternative packages

     FreeBSD packages for tuptime can be found at the following URLs

       FreeBSD 10 64bit:  http://pkg.ssnet.ca/10amd64-default/All/tuptime-3.2.01.txz
       FreeBSD 10 32bit:  http://pkg.ssnet.ca/10i386-default/All/tuptime-3.2.01.txz

       FreeBSD 11 64bit:  http://pkg.ssnet.ca/11amd64-default/All/tuptime-3.2.01.txz
       FreeBSD 11 ARMv6:  http://pkg.ssnet.ca/11armv6-default/All/tuptime-3.2.01.txz

     After downloading the correct package you can install it using pkg:

       # pkg add tuptime-3.2.01.txz
       # echo 'tuptime_enable="YES"' >> /etc/rc.conf

     Add an entry to /etc/crontab
         */5     *       *       *       *       root	/usr/local/bin/tuptime -x

   + Manual install

      Clone repository and copy executable file:

         # cp tuptime/latest/tuptime /usr/local/bin/tuptime
         # chmod 755 /usr/local/bin/tuptime 

      Add an entry to /etc/crontab

         */5     *       *       *       *       root    /usr/local/bin/tuptime -x

      Copy rc.d file:

         # cp tuptime/latest/rc.d/tuptime-freebsd /usr/local/etc/rc.d/tuptime
         # chmod 555 /usr/local/etc/rc.d/tuptime
         # echo 'tuptime_enable="YES"' >> /etc/rc.conf


For OSX system:

   Tuptime is compatible with OSX but, for now, the project lacks of launchd files
   for the startup and the schedule run.



============================
| Command line  parameters |
============================

These are the command line options, no configuration file is used:

  -h, --help            show this help message and exit
  -c, --ckernel         classify / order by kernel
  -d DATE_FORMAT, --date=DATE_FORMAT
                        date format output
  -e, --end             order by end state
  -f FILE, --filedb=FILE
                        database file
  -g, --graceful        register a gracefully shutdown
  -k, --kernel          print kernel information
  -l, --list            enumerate system life as list
  -o, --offtime         order by offtime / downtime
  -r, --reverse         reverse order
  -s, --seconds         output time in seconds and epoch
  -t, --table           enumerate system life as table
  -u, --uptime          order by uptime
  -v, --verbose         verbose output
  -V, --version         show version
  -x, --silent          update values into db without output


-h, --help
  Print a quick reference of the command line parameters.

  Examples:
         tuptime -h
         tuptime --help


-c, --ckernel
  Order table or list by kernel name. Therefore, only works in conjunction 
  with (-k) and (-t) or (-l) options.

  Examples:
         tuptime -ckl
         tuptime -ckt
         tuptime -t --ckernel
         tuptime -l --ckernel


-d <DATE_FORMAT>, --date=<DATE_FORMAT>
  Change the date format. By default it's printed based on system locales.
  Allow values are:

	%a	Weekday as locale’s abbreviated name.
	%A	Weekday as locale’s full name.
	%w	Weekday as a decimal number, where 0 is Sunday and 6 is 
		Saturday.
	%d	Day of the month as a zero-padded decimal number.
	%b	Month as locale’s abbreviated name.
	%B	Month as locale’s full name.
	%m	Month as a zero-padded decimal number.
	%y	Year without century as a zero-padded decimal number.
	%Y	Year with century as a decimal number.
	%H	Hour (24-hour clock) as a zero-padded decimal number.
	%I	Hour (12-hour clock) as a zero-padded decimal number.
	%p	Locale’s equivalent of either AM or PM.
	%M	Minute as a zero-padded decimal number.
	%S	Second as a zero-padded decimal number.
	%f	Microsecond as a decimal number, zero-padded on the left.
	%z	UTC offset in the form +HHMM or -HHMM (empty string if the 
		the object is naive).
	%Z	Time zone name (empty string if the object is naive).
	%j	Day of the year as a zero-padded decimal number.
	%U	Week number of the year (Sunday as the first day of the week) 
		as a zero padded decimal number. All days in a new year 
		preceding the first Sunday are considered to be in week 0.
	%W	Week number of the year (Monday as the first day of the week) 
		as a decimal number. All days in a new year preceding the 
		first Monday are considered to be in week 0.
	%c	Locale’s appropriate date and time representation.
	%x	Locale’s appropriate date representation.
	%X	Locale’s appropriate time representation.
	%%	A literal '%' character.


  Examples:
         tuptime -d '%X %x'  # (Default)
         tuptime -d '%H:%M:%S   %m-%d-%Y'  # British style
         tuptime -d '%H:%M:%S   %d-%b-%Y'  # Spanish style


-e, --end
  Order table or list by end status at power off. Therefore, only works 
  in conjunction with (-t) or (-l) options.

  Examples:
         tuptime -te
         tuptime -le
         tuptime -t --end
         tuptime -l --end


-f <FILE>, --filedb=<FILE>
  Define an alternative database file. Default is located in 
  '/var/lib/tuptime/tuptime.db'

  Examples:
         tuptime -f /var/lib/tuptime/tuptime.db  # (Default)
         tuptime -f /tmp/test1.db
         tuptime --filedb /tmp/test2.db

  
-g, --graceful
  Register last time in the db as a graceful shutdown. This option is the way
  that tuptime have for know if is a good or a bad shutdown, like a hang of the
  system, for example. This is used in the init.d and systemd files at the 
  shutdown process.

  Examples:
         tuptime -g
         tuptime --graceful


-k, --kernel
  Add kernel information to the output.

  Examples:
         tuptime -k
         tuptime -lk
         tuptime --kernel
         tuptime -t --kernel


-l, --list
  Enumerate as list each startup number, startup date, uptime, shutdown date, 
  end status and offtime. Multiple order options can be combined together.

  Examples:
         tuptimoe -l
         tuptimoe --list


-o, --offtime
  Order table or list by offtime / downtime. Therefore, only works in conjunction with 
  (-t) or (-l) options.

  Examples:
         tuptime -to
         tuptime -lo
         tuptime -t --offtime
         tuptime -l --offtime


-r, --reverse
  Reverse the order for table or list output. Therefore, only works in conjunction with 
  any of (-t), (-l), (-e), (-o), (-u) and (-c) options.

  Examples:
         tuptime -tr
         tuptime -lur
         tuptime -teo --reverse
         tuptime -l --reverse


-s, --seconds
  Change default human readable date style and print times in seconds and
  dates in epoch.

  Examples:
         tuptime -s
         tuptime --seconds


-t, --table
  Enumerate as table each startup number, startup date, uptime, shutdown date, 
  end status and downtime. Multiple order options can be combined together.

  Examples:
         tuptimoe -t
         tuptimoe --table


-u, --uptime
  Order table or list by uptime. Therefore, only works in conjunction with 
  (-t) or (-l) options.

  Examples:
         tuptime -tu
         tuptime -lu
         tuptime -t --uptime
         tuptime -l --uptime


-v, --verbose
  Print information about the internals of tuptime. It's good for debugging 
  how it gets the variables.

  Examples:
         tuptime -v
         tuptime --verbose


-V, --version:
  Print version number and exit.

  Examples:
         tuptime -V
         tuptime --version


-x, --silent
  Any output is printed. Only update values and save them into disk.

  Examples:
         tuptime -x
         tuptime --silent



======================
| Schedule execution |
======================

It's importat to have a schedule execution. If the init or systemd scripts
are installed as it needs, the program only update values at startup and 
shutdown, but if the system fails, hangs or whatever, the uptime time will
be lost. Be sure that the cron entry is installed as expected.



=============================================
| DB format changes from 2.x to 3.x version |
=============================================

If this error appears:

...(a few lines)...
sqlite3.OperationalError: no such column: endst

or:

...(a few lines)...
    db_rows[-1][4] = opt.endst
IndexError: list assignment index out of range

Is because the database have the format of the 2.x release. For migrate it, 
please, execute the script "db-tuptime-migrate.sh" which is located at:

https://github.com/rfrail3/tuptime/blob/master/scripts/db-tuptime-migrate.sh
 


=====================================
| Reset and modify or delete values |
=====================================

Tuptime use a sqlite3 database located in "/var/lib/tuptime/tuptime.db" with
the following format:

tuptime (btime integer, 
         uptime real, 
         offbtime integer, 
         endst integer, 
         downtime real, 
         kernel text)

For reset all the values, simply detele the database file.

Is it possible to query and modify it directly. But if a complete row is
deleted and the db is not recreate completely (vacuum), rowid keep the real
information about startup number. Tuptime will advert about it if the verbose
mode is enabled.



================
| Some Toughts |
================

Usually the installation is made with a privileged user, for that reason,
the database file is created with restricted permissions and the unprivileged
users can only read it. This situation is covered for print values, but 
not for update database. In this habitual case, a privileged user need to
execute tuptime for update values at startup and shutdown at least.

Kernel name is registered each time that tuptime update values. If ksplice is
used to update the kernel, last kernel will have the whole time asignement
since the last system start.

Table output can be processed with awk, for example:

   # tuptime -t | awk -F'[[:space:]][[:space:]][[:space:]]*' '{print $1}'
