RackTables Wiki - User contributions [en]

ProjectInfrastructure

2024-02-25T18:53:31Z

Infrastation: /* git mirrors (code) */ git.racktables.org replaces code.racktables.org

==Mapping of assets==
=== DNS ===
racktables.org domain is currently registered through GoDaddy, which also provides 2 free nameservers. Aaron manages the domain.

=== racktables.org mail ===
racktables.org mail is handled by zohomail.com. Zoho Mail offers free service for up to three e-mail addresses. Two mailing lists exist, "devteam" and "info", which are setup to forward all messages to every development team member.

=== racktables-users mail ===
FreeLists is a great free service without accompanying advertisements. The only drawback about it is that it is non-profit and can go down some day, hence '''make sure the list of subscribers is present in a recent backup tarball'''.

To manage the mailing list, go to [http://www.freelists.org/login.html this page] and use the form to the left. Input your email subscribed to the list. If you don't remember your password, log in with an empty password, in this case the system will email you a one-time token to input on the next screen. Once logged in, you will see a very long SELECT with all lists of FreeLists. Click on the SELECT and press "r" to get to items starting with R. Select racktables-users and press "Select list" below. On the next screen press "Admin Menu". To manage individual subscribers, select one on the "Current List Users" SELECT and press "User Options". VACATION, MODPOST and NOPOST are the most frequently used flags, their meaning is explained inline.

Please think twice before changing any of the list-wide settings on the "Edit List Config" menu, these settings influence all subscribers of racktables-users.

=== Most web-sites (demo, bugs, wiki, www) ===
Arnaud Launay is the server administrator. To get SSH access there, be a team member and find someone who already has access.

=== git mirrors (code) ===
The [https://git.racktables.org/ git mirror server] exists to provide backups in case github.com goes kaput. The most up to date copies are available through both a web-interface (gitweb) and git clone URLs, for example:
git clone https://git.racktables.org/racktables
Cloning into 'racktables'...
The server synchronizes each repository both hourly and after a new commit appears on github.com (via a webhook). It also keeps up to 90 days of backups for every repository.

This cannot be hosted with the other servers because the git mirror server notifies the MantisBT server so the source control integration fetches new changes into its database. However, the TCP connection does not establish within the same network, it needs to originate from outside.

=== Statistics ===
SF download stats work for the downloads. Google analytics was used in the past for racktables.org and demo.racktables.org, but was removed in 2019.

=== downloads ===
SourceForge project FRS (File Release System, a CDN of sorts).
----

==Backup procedure==
===the backup directory===
mkdir RackTables-project-backup-`date +%Y%m%d`
cd RackTables-project-backup-`date +%Y%m%d`

===racktables-users mailing list===
Send an empty email with subject "who racktables-users" to ecartis@freelists.org and you will get a list of all subscribers. Save it to the backup directory as "racktables-users.txt".

===Git repositories===
git clone --mirror git://github.com/RackTables/racktables.git racktables.git
git clone --mirror git://github.com/RackTables/racktables-contribs.git racktables-contribs.git

===Bug tracker, wiki data, www===
SSH into the host and create a new backup directory.
mkdir ~/RackTables-apps-backup
cd ~/RackTables-apps-backup

Copy the applications into the backup directory on the server. This is important because they contain uploaded files and configuration settings.
tar czf bugs.tar.gz ~/www/bugs
tar czf wiki.tar.gz ~/www/wiki
tar czf www.tar.gz ~/www/www

Export the database for each application.
mysqldump -u <username> -p <dbname> > bugs.sql
mysqldump -u <username> -p <dbname> > wiki.sql

SCP the remote server directory to the local backup directory, then remove it from the server.

===Final check===
Now the backup directory must have these files/directories:
* racktables.git
* racktables-contribs.git
* racktables-users.txt
* RackTables-apps-backup
** wiki.tar.gz
** wiki.sql
** bugs.tar.gz
** bugs.sql
** www.tar.gz
'''SAVE THE BACKUP FOLDER TO A SAFE PLACE'''

ProjectInfrastructure

2022-11-13T19:03:58Z

Infrastation: /* Statistics */ Google Analytics was retired three years ago.

==Mapping of assets==
=== DNS ===
racktables.org domain is currently registered through GoDaddy, which also provides 2 free nameservers. Aaron manages the domain.

=== racktables.org mail ===
racktables.org mail is handled by zohomail.com. Zoho Mail offers free service for up to three e-mail addresses. Two mailing lists exist, "devteam" and "info", which are setup to forward all messages to every development team member.

=== racktables-users mail ===
FreeLists is a great free service without accompanying advertisements. The only drawback about it is that it is non-profit and can go down some day, hence '''make sure the list of subscribers is present in a recent backup tarball'''.

To manage the mailing list, go to [http://www.freelists.org/login.html this page] and use the form to the left. Input your email subscribed to the list. If you don't remember your password, log in with an empty password, in this case the system will email you a one-time token to input on the next screen. Once logged in, you will see a very long SELECT with all lists of FreeLists. Click on the SELECT and press "r" to get to items starting with R. Select racktables-users and press "Select list" below. On the next screen press "Admin Menu". To manage individual subscribers, select one on the "Current List Users" SELECT and press "User Options". VACATION, MODPOST and NOPOST are the most frequently used flags, their meaning is explained inline.

Please think twice before changing any of the list-wide settings on the "Edit List Config" menu, these settings influence all subscribers of racktables-users.

=== Most web-sites (demo, bugs, wiki, www) ===
Arnaud Launay is the server administrator. To get SSH access there, be a team member and find someone who already has access.

=== git mirrors (code) ===
The [https://code.racktables.org/ git mirror server] exists to provide backups in case github.com goes kaput. The most up to date copies are available through both a web-interface (gitweb) and git clone URLs, for example:
git clone https://code.racktables.org/racktables
Cloning into 'racktables'...
The server synchronizes each repository both hourly and after a new commit appears on github.com (via a webhook). It also keeps up to 90 days of backups for every repository.

This cannot be hosted with the other servers because the git mirror server notifies the MantisBT server so the source control integration fetches new changes into its database. However, the TCP connection does not establish within the same network, it needs to originate from outside.

=== Statistics ===
SF download stats work for the downloads. Google analytics was used in the past for racktables.org and demo.racktables.org, but was removed in 2019.

=== downloads ===
SourceForge project FRS (File Release System, a CDN of sorts).
----

==Backup procedure==
===the backup directory===
mkdir RackTables-project-backup-`date +%Y%m%d`
cd RackTables-project-backup-`date +%Y%m%d`

===racktables-users mailing list===
Send an empty email with subject "who racktables-users" to ecartis@freelists.org and you will get a list of all subscribers. Save it to the backup directory as "racktables-users.txt".

===Git repositories===
git clone --mirror git://github.com/RackTables/racktables.git racktables.git
git clone --mirror git://github.com/RackTables/racktables-contribs.git racktables-contribs.git

===Bug tracker, wiki data, www===
SSH into the host and create a new backup directory.
mkdir ~/RackTables-apps-backup
cd ~/RackTables-apps-backup

Copy the applications into the backup directory on the server. This is important because they contain uploaded files and configuration settings.
tar czf bugs.tar.gz ~/www/bugs
tar czf wiki.tar.gz ~/www/wiki
tar czf www.tar.gz ~/www/www

Export the database for each application.
mysqldump -u <username> -p <dbname> > bugs.sql
mysqldump -u <username> -p <dbname> > wiki.sql

SCP the remote server directory to the local backup directory, then remove it from the server.

===Final check===
Now the backup directory must have these files/directories:
* racktables.git
* racktables-contribs.git
* racktables-users.txt
* RackTables-apps-backup
** wiki.tar.gz
** wiki.sql
** bugs.tar.gz
** bugs.sql
** www.tar.gz
'''SAVE THE BACKUP FOLDER TO A SAFE PLACE'''

NewRelease

2022-02-16T13:06:39Z

Infrastation: /* updating demo */ use "git add -p"

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git add ChangeLog wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -p</tt> the new file again (note the flag). Add relevant chunks only. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo yes
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

NewRelease

2022-02-15T20:30:27Z

Infrastation: The CI was Travis, but it isn't anymore.

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git add ChangeLog wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo yes
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

ProjectInfrastructure

2021-08-20T18:46:24Z

Infrastation: describe code.racktables.org

==Mapping of assets==
=== DNS ===
racktables.org domain is currently registered through GoDaddy, which also provides 2 free nameservers. Aaron manages the domain.

=== racktables.org mail ===
racktables.org mail is handled by zohomail.com. Zoho Mail offers free service for up to three e-mail addresses. Two mailing lists exist, "devteam" and "info", which are setup to forward all messages to every development team member.

=== racktables-users mail ===
FreeLists is a great free service without accompanying advertisements. The only drawback about it is that it is non-profit and can go down some day, hence '''make sure the list of subscribers is present in a recent backup tarball'''.

To manage the mailing list, go to [http://www.freelists.org/login.html this page] and use the form to the left. Input your email subscribed to the list. If you don't remember your password, log in with an empty password, in this case the system will email you a one-time token to input on the next screen. Once logged in, you will see a very long SELECT with all lists of FreeLists. Click on the SELECT and press "r" to get to items starting with R. Select racktables-users and press "Select list" below. On the next screen press "Admin Menu". To manage individual subscribers, select one on the "Current List Users" SELECT and press "User Options". VACATION, MODPOST and NOPOST are the most frequently used flags, their meaning is explained inline.

Please think twice before changing any of the list-wide settings on the "Edit List Config" menu, these settings influence all subscribers of racktables-users.

=== Most web-sites (demo, bugs, wiki, www) ===
Arnaud Launay is the server administrator. To get SSH access there, be a team member and find someone who already has access.

=== git mirrors (code) ===
The [https://code.racktables.org/ git mirror server] exists to provide backups in case github.com goes kaput. The most up to date copies are available through both a web-interface (gitweb) and git clone URLs, for example:
git clone https://code.racktables.org/racktables
Cloning into 'racktables'...
The server synchronizes each repository both hourly and after a new commit appears on github.com (via a webhook). It also keeps up to 90 days of backups for every repository.

This cannot be hosted with the other servers because the git mirror server notifies the MantisBT server so the source control integration fetches new changes into its database. However, the TCP connection does not establish within the same network, it needs to originate from outside.

=== Statistics ===
SF download stats work for the downloads. Google analytics works for the content of racktables.org and demo.racktables.org (it does not currently display its admin interface in every browser).

=== downloads ===
SourceForge project FRS (File Release System, a CDN of sorts).
----

==Backup procedure==
===the backup directory===
mkdir RackTables-project-backup-`date +%Y%m%d`
cd RackTables-project-backup-`date +%Y%m%d`

===racktables-users mailing list===
Send an empty email with subject "who racktables-users" to ecartis@freelists.org and you will get a list of all subscribers. Save it to the backup directory as "racktables-users.txt".

===Git repositories===
git clone --mirror git://github.com/RackTables/racktables.git racktables.git
git clone --mirror git://github.com/RackTables/racktables-contribs.git racktables-contribs.git

===Bug tracker, wiki data, www===
SSH into the host and create a new backup directory.
mkdir ~/RackTables-apps-backup
cd ~/RackTables-apps-backup

Copy the applications into the backup directory on the server. This is important because they contain uploaded files and configuration settings.
tar czf bugs.tar.gz ~/www/bugs
tar czf wiki.tar.gz ~/www/wiki
tar czf www.tar.gz ~/www/www

Export the database for each application.
mysqldump -u <username> -p <dbname> > bugs.sql
mysqldump -u <username> -p <dbname> > wiki.sql

SCP the remote server directory to the local backup directory, then remove it from the server.

===Final check===
Now the backup directory must have these files/directories:
* racktables.git
* racktables-contribs.git
* racktables-users.txt
* RackTables-apps-backup
** wiki.tar.gz
** wiki.sql
** bugs.tar.gz
** bugs.sql
** www.tar.gz
'''SAVE THE BACKUP FOLDER TO A SAFE PLACE'''

Gateways

2021-07-23T12:47:06Z

Infrastation: Reformat the tables for a more modern visual style.

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| class="wikitable"
!Breed Code
!Description
|-
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| class="wikitable"
!Command Code
!Description
|-
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table (for all ports) as an array.
|-
| <tt>getportmaclist</tt>
| Returns the MAC address table (for a specific port only) as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}

==Implementation matrix==
{| class="wikitable" style="text-align:center;"
|
! <tt>xlatepushq</tt>
! <tt>get8021q</tt>
! <tt>getallconf</tt>
! <tt>getcdpstatus</tt>
! <tt>getlldpstatus</tt>
! <tt>getmaclist</tt>
! <tt>getportmaclist</tt>
! <tt>getportstatus</tt>
! <tt>getinventory</tt>
|-
! style="text-align:left;" | <tt>air12</tt>
| ✓
|
| ✓
|
|
|
|
|
|
|-
! style="text-align:left;" | <tt>dlink</tt>
| ✓
| ✓
|
|
|
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>eos4</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>fdry5</tt>
| ✓
| ✓
| ✓
|
|
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>ftos8</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>hpprocurveN1178</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>ios12</tt>
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>ios15</tt>
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>iosxr4</tt>
| ✓
|
| ✓
|
|
|
|
|
|
|-
! style="text-align:left;" | <tt>jun10</tt>
| ✓
| ✓
| ✓
|
|
|
|
|
|
|-
! style="text-align:left;" | <tt>linux</tt>
| ✓
| ✓
|
|
|
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>nxos4</tt>
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>ros11</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>ucs</tt>
| ✓
|
|
|
|
|
|
|
| ✓
|-
! style="text-align:left;" | <tt>vrp53</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>vrp55</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>vrp85</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|-
! style="text-align:left;" | <tt>xos12</tt>
| ✓
| ✓
| ✓
|
| ✓
| ✓
| ✓
| ✓
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Plugins

2021-07-23T11:58:59Z

Infrastation: Use fixed-width style for pathnames and PHP code, lose some passive voice, use m-dashes and arrows.

== Overview ==
Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.

=== States ===
A plugin may be in one of three states.
* Not installed — it exists in the plugins directory, but hasn't been installed yet
* Enabled — it has been installed and is active
* Disabled — it has been installed and was subsequently disabled

=== Administration ===
To install a plugin, first copy it to the <code>plugins</code> directory. Then visit the Configuration → Plugins page and click the Edit tab. The new plugin should be listed with a state of "Not installed". Click the Install icon.

To upgrade a plugin, first backup the appropriate <code>plugins</code> sub-directory. To be safe, it's also a good idea to backup your entire database. Afterwards, copy over the new version into the <code>plugins</code> directory. When you visit the Edit tab of the Configuration → Plugins page, you should see a variance in the Code Version and DB Version columns. Click the Upgrade icon.

== Writing a Plugin ==
The old procedure involves placing a PHP file in the <code>plugins</code> directory of your RackTables installation. That method has limited functionality and may be deprecated at a later date.

RackTables release 0.21.0 had introduced a new plugin architecture, which includes the ability to install, uninstall, enable and disable plugins from the web interface. It is assumed that each plugin resides in its own directory within the main <code>plugins</code> directory, and that each plugin contains a <code>plugin.php</code> file which includes certain functions. The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.

=== Files ===
Each plugin is expected to contain certain files. While the only required file is <code>plugin.php</code>, it is recommended that you include all mentioned files, especially if you intend to publish it for others.

* <code>README</code> — Provide a general description. If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.
* <code>ChangeLog</code> — Document changes made to each revision.
* <code>LICENSE</code>

=== Functions ===
{| class="wikitable"
!Name
!Returns
!Description
|-
|<code>plugin_PLUGINNAME_info()</code>
|array
|Array keys are <code>name</code>, <code>longname</code>, <code>version</code> and <code>home_url</code>.
|-
|<code>plugin_PLUGINNAME_init()</code>
|void
|Initialize the plugin. Register pages, tabs, triggers, handlers, etc.
|-
|<code>plugin_PLUGINNAME_install()</code>
|boolean
|Make any necessary modifications (create tables, create Config settings, etc.)
|-
|<code>plugin_PLUGINNAME_uninstall()</code>
|boolean
|Make any necessary modifications (drop tables, delete Config settings, etc.)
|-
|<code>plugin_PLUGINNAME_upgrade()</code>
|boolean
|Make any necessary modifications (alter tables, modify Config settings, etc.)
|-
|<code>plugin_PLUGINNAME_HOOKNAME()</code>
|varies
|Run when called by a system-level function (described below in the Hooks section)
|}

=== Hooks ===
These are used in cases where custom functions defined by a plugin should be called at specific times.

Examples:
* When resetting or deleting an object
* Resetting the Config settings (Configuration → User interface)
* Viewing the Data Integrity report

Hooks are already supported in some functions, such as <code>commitResetObject()</code>. If you need it supported by another function, create a GitHub pull request and it will probably be accepted.

=== Upgrades ===
The <code>plugin_PLUGINNAME_upgrade()</code> function is mandatory. If this is the first version, or if no upgrade steps are required, simply have the function return <code>TRUE</code>.

There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information. These transitions should be handled by the upgrade function.

Example modeled after the core RackTables upgrader:

<pre>
function plugin_myplugin_upgrade ()
{
$db_info = getPlugin ('myplugin');
$v1 = $db_info['db_version'];
$code_info = plugin_plugin_info ();
$v2 = $code_info['version'];

if ($v1 == $v2)
throw new RackTablesError ('Versions are identical', RackTablesError::INTERNAL);

// find the upgrade path to be taken
$versionhistory = array
(
'1.0',
'2.0',
'3.0'
);
$skip = TRUE;
$path = NULL;
foreach ($versionhistory as $v)
{
if ($skip and $v == $v1)
{
$skip = FALSE;
$path = array();
continue;
}
if ($skip)
continue;
$path[] = $v;
if ($v == $v2)
break;
}
if ($path === NULL or ! count ($path))
throw new RackTablesError ('Unable to determine upgrade path', RackTablesError::INTERNAL);

// build the list of queries to execute
$queries = array ();
foreach ($path as $batchid)
{
switch ($batchid)
{
case '2.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '2.0' WHERE name = 'myplugin'";
break;
case '3.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '3.0' WHERE name = 'myplugin'";
break;
default:
throw new RackTablesError ("Preparing to upgrade to $batchid failed", RackTablesError::INTERNAL);
}
}

// execute the queries
global $dbxlink;
foreach ($queries as $q)
{
try
{
$result = $dbxlink->query ($q);
}
catch (PDOException $e)
{
$errorInfo = $dbxlink->errorInfo();
throw new RackTablesError ("Query: ${errorInfo[2]}", RackTablesError::INTERNAL);
}
}
}
</pre>

NewRelease

2020-10-05T18:03:18Z

Infrastation: /* updating demo */ I had retired Google Analytics from this job a while ago.

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git add ChangeLog wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo yes
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

SourceCode

2020-09-03T12:10:45Z

Infrastation: squash two PHP version sections into one

== the source code repository==
RackTables project uses git as version control system for the source code ([https://github.com/RackTables/racktables GitHub], [https://code.racktables.org/ read-only mirror]). The repository includes the following notable branches:
;master
:The main development branch, that is, the default branch for all new changes.
;maintenance-0.21.x
:The maintenance branch for 0.21.x stable releases (see the roadmap).
;maintenance-0.20.x
;maintenance-0.19.x
;maintenance-0.18.x
;maintenance-0.17.x
;maintenance-0.16.x
:Archived maintenance branches, which do not accept any new changes.

Use the following commands to get a working copy of the repository:
<pre>
# from the RackTables project repository
git clone git://github.com/RackTables/racktables.git
# or
git clone https://github.com/RackTables/racktables.git
# or
git clone ssh://git@github.com:RackTables/racktables.git

# from a GitHub fork (of your own or not)
git clone git://github.com/username/racktables.git
# or
git clone https://github.com/username/racktables.git
# or
git clone ssh://git@github.com:username/racktables.git
</pre>
Note that the first two schemas (<tt>git://</tt> and <tt>https://</tt>) are always '''read-only''' and the third (<tt>ssh://</tt>) may be '''read-only or read-write'''.

Use the following commands to examine local unsaved changes:
<pre>
git status
git diff
</pre>

The recommended way of contributing the work is to:
# fork RackTables on GitHub,
# push finished commits to the fork, and
# create a pull request.

In the case of a private repository use a [http://git-scm.com/docs/git-format-patch git format-patch] command to produce a patch and send it to the developers. When sending a patch, please make sure your branch is [http://git-scm.com/book/en/Git-Branching-Rebasing rebased] onto the latest respective (master or maintenance) branch.

== PHP code style guide ==
Almost all PHP source code in RackTables is original and the following style guide applies:
==== use [http://en.wikipedia.org/wiki/Indent_style#Allman_style Allman] indent style. ====
'''Why:''' Allman style is very diff-friendly when it comes to control structures. In Allman style expansion of a single inner operator into a larger code block (and vice versa) leaves both the inner (controlled) and the outer (controlling) operator intact:
<pre>
for ($i = 0; $i < 10; $i++)
+{
doSomething ($i);
+ doSomethingElse();
+}
</pre>
This works seamlessly at any indentation level and for all control structures (<tt>if/for/foreach/while</tt>), however deeply nested in each other. With careful indentation of <tt>case</tt> within <tt>switch</tt> it will work same well:
<pre>
switch ($var)
{
case 1:
doSomething();
break;
case 2:
- {
- doSomethingElse();
return 3;
- }
case 3:
+ {
+ doSomethingCompletelyDifferent();
return 4;
+ }
}
</pre>
Being diff-friendly means being friendly to a version control system (Subversion in the past, git at present). Neither the VCS nor the Allman style alone guarantee one's commits to be focused and clean. However, Allman style encourages commits that change only the lines that really need to be changed.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

==== use exactly one tab per indentation level ====
'''Why:''' different people prefer different (2, 4, 8...) amount of "spaces" per indentation level. Some projects use space indentation and force everyone to hit Space (Backspace) N times each time the developer needs to indent (unindent), regardless of their own preferred value of N. RackTables makes use of Tab and enables every developer to configure their editor for their preferred "tab width" (the screenshot below stands for tab width 2). Note that the tab width must stand for the amount of spaces the editor ''displays'', but not ''generates instead of'', that is, in the source file '''tabs must remain tabs'''.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

[[File:interface_tab2.png]]

==== wrap lines longer than 100-120 characters ====
'''Why:''' readability. Prior experience tells that old-school 80-columns margin just doesn't work with descriptive naming of variables and functions (i.e. descriptive == heavily wrapped). On the other hand, avoid making a readable, 200-characters long line even if it fits your monitor. Use good judgement.

==== consider using indentation/alignment for function arguments ====
'''Why:''' the purpose is twofold. On one hand it allows to pack a lot of arguments and expressions into a single function call without losing track of what is being done and no temporary variables:
<pre>
usePreparedUpdateBlade
(
'Port',
array
(
'name' => $port_name,
'type' => $port_type_id,
'label' => $port_label,
'reservation_comment' => $reservation_comment,
'l2address' => nullEmptyStr ($db_l2address),
),
array
(
'id' => $port_id,
'object_id' => $object_id
)
);
</pre>
On the other hand, it allows to group function arguments add/or add comments to them:
<pre>
function get8021QSyncOptions
(
$vswitch,
$D, // desired config
$C, // cached config
$R // running-config
)
{
$default_port = array
(
'mode' => 'access',
'allowed' => array (VLAN_DFL_ID),
'native' => VLAN_DFL_ID,
);
$ret = array();
</pre>
Use good judgement.

==== consider using indentation/alignment for arrays ====
'''Why:''' due to a few reasons. First, multiline array assignment/initialization can accommodate a notable amount of supplementary expressions:
<pre>
$ret[$pn] = array
(
'status' => 'martian_conflict',
'left' => array_key_exists ($pn, $C) ? $C[$pn] : array ('mode' => 'none'),
'right' => array_key_exists ($pn, $R) ? $R[$pn] : array ('mode' => 'none'),
);
</pre>
Second, updates to arrays that serve as lists produce cleaner diffs, for example:
<pre>
--- a/wwwroot/inc/remote.php
+++ b/wwwroot/inc/remote.php
@@ -64,6 +64,7 @@ $breedfunc = array
'jun10-get8021q-main' => 'jun10Read8021QConfig',
'jun10-xlatepushq-main' => 'jun10TranslatePushQueue',
'jun10-getallconf-main' => 'jun10SpotConfigText',
+ 'jun10-getlldpstatus-main' => 'jun10ReadLLDPStatus',
'ftos8-xlatepushq-main' => 'ftos8TranslatePushQueue',
'ftos8-getlldpstatus-main' => 'ftos8ReadLLDPStatus',
'ftos8-getmaclist-main' => 'ftos8ReadMacList',
</pre>
Finally, it makes tree-like array initialization more transparent:
<pre>
$SQLSchema = array
(
'object' => array
(
'table' => 'RackObject',
'columns' => array
(
'id' => 'id',
'name' => 'name',
'label' => 'label',
'asset_no' => 'asset_no',
'objtype_id' => 'objtype_id',
'rack_id' => '(SELECT MIN(rack_id) FROM RackSpace WHERE object_id = RackObject.id)',
'rack_id_2' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'rack')",
'container_id' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'object')",
'container_name' => '(SELECT name FROM RackObject WHERE id = container_id)',
'container_objtype_id' => '(SELECT objtype_id FROM RackObject WHERE id = container_id)',
'has_problems' => 'has_problems',
'comment' => 'comment',
'nports' => '(SELECT COUNT(*) FROM Port WHERE object_id = RackObject.id)',
'8021q_domain_id' => '(SELECT domain_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
'8021q_template_id' => '(SELECT template_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
),
'keycolumn' => 'id',
'ordcolumns' => array ('RackObject.name'),
),
</pre>

==== put <tt>else</tt> near its <tt>if</tt> ====
When an <tt>if</tt> operator includes the <tt>else</tt> part, consider arranging the branches so that the short branch belongs to the <tt>if</tt> and the long branch belongs to the <tt>else</tt>. '''Why:''' it helps following the code.

Holub, Allen (1995). Enough Rope to Shoot Yourself in the Foot. McGraw-Hill. ISBN 978-0-07-029689-3
"Section 57: Put the shortest clause of an <tt>if/else</tt> on top."

==== use the [http://en.wikipedia.org/wiki/%3F: conditional ternary operator] where it makes sense ====
'''Why:''' to use the language element in making the code look closer to what the code is intended to do. First, don't reinvent the conditional ternary operator with <tt>if</tt> like this:
<pre>
if ($row !== FALSE)
return $row[0];
else
return NULL;
</pre>
That block of code returns a value in either case, exactly one <tt>return</tt> would do the job:
<pre>
return $row === FALSE ? NULL : $row[0];
</pre>

Second, don't nest ternary conditionals, it is hard to read:
<pre>
$ret = ($ret > 0 ? 1 : ($ret < 0 ? -1 : 0));
</pre>
For that specific case use <tt>numSign()</tt>.

Finally, when a standalone ternary conditional isn't sufficient or is long/difficult to read, use temporary variables or necessary amount of <tt>if</tt>'s.

==== things to consider when adding a new function ====
* First, is it possible to use one of the existing functions or a combination of these?
* Carefully decide which file the function should be in (depends on its purpose and relation to other functions).
* Consider [http://en.wikipedia.org/wiki/CamelCase headlessCamelCase] for the function name.
* Try to keep functions focused, that is, small, doing just one thing but doing it very well.
* When adding a new function, add unit test(s) for it as well.

==== put <tt>$self = __FUNCTION__;</tt> at the beginning of a recursive function ====
'''Why:''' to make it easier to see a recursive function. Such a function should call itself as <tt>$self(...)</tt> so that if the function is renamed later its code requires no changes to work.
<pre>
# Return a list consisting of tag ID of the given tree node and IDs of all
# nodes it contains.
function getTagIDListForNode ($treenode)
{
$self = __FUNCTION__;
$ret = array ($treenode['id']);
foreach ($treenode['kids'] as $item)
$ret = array_merge ($ret, $self ($item));
return $ret;
}
</pre>

==== prefer <tt>//</tt> over <tt>#</tt> for single-line comments ====
'''Why:''' it saves keystokes (double-press one key versus pressing two different keys simultaneously). However, when adding a comment to a code that already uses <tt>#</tt>, be consistent with what is already there.
Also, the code contains ~ 2000 of //-style lines versus ~450 of #-style.

==== don't use <tt>foreach()</tt> by reference ====
'''Why:''' this valid language construct has a side effect that complicates things. Consider the following code:
<pre>
$a = array (1 => 'a', 2 => 'b', 3 => 'c');
foreach ($a as &$tmp)
$tmp = $tmp . '_str';
</pre>
So far so good, but once you decide to reuse <tt>$tmp</tt> and assign a new value to it, you will [unexpectedly] modify the array (<tt>$tmp</tt> still holds the reference to the last element). [https://bugs.php.net/bug.php?id=37410 This thread] discusses the workings of this at length. The workaround would be to use <tt>unset ($tmp)</tt> after the foreach-by-reference, but the least-surprising solution is to iterate over array keys if you need to modify array elements and <tt>array_walk()</tt> is not sufficient:
<pre>
foreach (array_keys ($a) as $k)
$a[$k] = $a[$k] . '_str';
</pre>

==== use double-quotes for strings only when necessary ====
'''Why:''' it saves the time required to tell "just strings" from strings that embed expansions. Consider the following:
<pre>
$string1 = 'Single-quotes give a hint that this string is just a string.';
$string2 = "Double-quotes give a hint that this string not just _may_ contain " .
"expansions but it actually does: here are $var1 and ${var2}";
</pre>

==== use <tt>array_key_exists()</tt> instead of <tt>isset()</tt> to test a key in an array ====
'''Why:''' with <tt>isset()</tt> it is impossible to distinguish a missing element from a typo in the array name:
<pre>
$arr = array (1 => 'a', 2 => 'b');
if (array_key_exists (10, $arr)) # FALSE
echo 'OK';
if (array_key_exists (10, $ar)) # FALSE and a PHP warning (note the typo)
echo 'OK';
if (isset ($arr[10])) # FALSE
echo 'OK';
if (isset ($ar[10])) # FALSE and no warning
echo 'OK';
</pre>

==== keep PHP code compatible with all supported PHP versions ====
'''Why:''' because newer PHP versions tend to deprecate functions and extensions, so you have to account for that.

==== use "&&" and "||", not "and" and "or" ====
'''Why:''' because (unlike, for instance, C++) those are not just alternative notations but quite different operators. From the [http://php.net/manual/en/language.operators.precedence.php PHP operator precedence table] it is possible to see that, for example, the following two lines of code work in a very different way:
<pre>
$c = $a or $b; // Evaluate $a and assign the value to $c. If $c was set to false, evaluate $b and discard the value.
$c = $a || $b; // Evaluate $a. If the value is true, set $c to true. Otherwise evaluate $b and assign the value to $c.
</pre>
Not everybody remembers about this difference and eventually interprets the code not as PHP actually executes it. As the gain of "and" and "or" in RackTables is negligible, the simplest solution is not to use them at all.

==== test for an empty string in the simplest way possible ====
Just compare with an empty string. Only use <tt>strlen()</tt> and <tt>mb_strlen()</tt> when those are really required, i.e. when it is necessary to know the exact length of a string or a multibyte string.
<pre>
if ($s == '') // OK
...
if ($s != '') // OK
...
if (strlen ($s)) // overkill
...
if (! strlen ($s)) // overkill
...
if (mb_strlen ($s)) // overkill
...
if (! mb_strlen ($s)) // overkill
...
</pre>

==== use uppercase for NULL, TRUE and FALSE ====
'''Why:''' because PHP documentation always spells it this way, so let's keep it readbale (PHP interpreter itself is case-insensitive in this regard).

== SQL code style guide ==
==== use uppercase for SQL keywords and wrap long lines ====
'''Why:''' readability
<pre>
$result = usePreparedSelectBlade
(
'SELECT FileLink.file_id, FileLink.id AS link_id, name, type, size, ctime, mtime, atime, comment ' .
'FROM FileLink LEFT JOIN File ON FileLink.file_id = File.id ' .
'WHERE FileLink.entity_type = ? AND FileLink.entity_id = ? ORDER BY name',
array ($entity_type, $entity_id)
);
</pre>

==== use SELECT with an explicit list of columns, don't use <tt>SELECT *</tt> ====
'''Why:''' this is very well explained in many sources, for instance, [http://stackoverflow.com/questions/3639861/why-is-select-considered-harmful here] and [http://use-the-index-luke.com/blog/2013-08/its-not-about-the-star-stupid here].

SourceCode

2020-09-03T12:08:13Z

Infrastation: /* make conscise use of the conditional ternary operator */ reword the section title

== the source code repository==
RackTables project uses git as version control system for the source code ([https://github.com/RackTables/racktables GitHub], [https://code.racktables.org/ read-only mirror]). The repository includes the following notable branches:
;master
:The main development branch, that is, the default branch for all new changes.
;maintenance-0.21.x
:The maintenance branch for 0.21.x stable releases (see the roadmap).
;maintenance-0.20.x
;maintenance-0.19.x
;maintenance-0.18.x
;maintenance-0.17.x
;maintenance-0.16.x
:Archived maintenance branches, which do not accept any new changes.

Use the following commands to get a working copy of the repository:
<pre>
# from the RackTables project repository
git clone git://github.com/RackTables/racktables.git
# or
git clone https://github.com/RackTables/racktables.git
# or
git clone ssh://git@github.com:RackTables/racktables.git

# from a GitHub fork (of your own or not)
git clone git://github.com/username/racktables.git
# or
git clone https://github.com/username/racktables.git
# or
git clone ssh://git@github.com:username/racktables.git
</pre>
Note that the first two schemas (<tt>git://</tt> and <tt>https://</tt>) are always '''read-only''' and the third (<tt>ssh://</tt>) may be '''read-only or read-write'''.

Use the following commands to examine local unsaved changes:
<pre>
git status
git diff
</pre>

The recommended way of contributing the work is to:
# fork RackTables on GitHub,
# push finished commits to the fork, and
# create a pull request.

In the case of a private repository use a [http://git-scm.com/docs/git-format-patch git format-patch] command to produce a patch and send it to the developers. When sending a patch, please make sure your branch is [http://git-scm.com/book/en/Git-Branching-Rebasing rebased] onto the latest respective (master or maintenance) branch.

== PHP code style guide ==
Almost all PHP source code in RackTables is original and the following style guide applies:
==== use [http://en.wikipedia.org/wiki/Indent_style#Allman_style Allman] indent style. ====
'''Why:''' Allman style is very diff-friendly when it comes to control structures. In Allman style expansion of a single inner operator into a larger code block (and vice versa) leaves both the inner (controlled) and the outer (controlling) operator intact:
<pre>
for ($i = 0; $i < 10; $i++)
+{
doSomething ($i);
+ doSomethingElse();
+}
</pre>
This works seamlessly at any indentation level and for all control structures (<tt>if/for/foreach/while</tt>), however deeply nested in each other. With careful indentation of <tt>case</tt> within <tt>switch</tt> it will work same well:
<pre>
switch ($var)
{
case 1:
doSomething();
break;
case 2:
- {
- doSomethingElse();
return 3;
- }
case 3:
+ {
+ doSomethingCompletelyDifferent();
return 4;
+ }
}
</pre>
Being diff-friendly means being friendly to a version control system (Subversion in the past, git at present). Neither the VCS nor the Allman style alone guarantee one's commits to be focused and clean. However, Allman style encourages commits that change only the lines that really need to be changed.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

==== use exactly one tab per indentation level ====
'''Why:''' different people prefer different (2, 4, 8...) amount of "spaces" per indentation level. Some projects use space indentation and force everyone to hit Space (Backspace) N times each time the developer needs to indent (unindent), regardless of their own preferred value of N. RackTables makes use of Tab and enables every developer to configure their editor for their preferred "tab width" (the screenshot below stands for tab width 2). Note that the tab width must stand for the amount of spaces the editor ''displays'', but not ''generates instead of'', that is, in the source file '''tabs must remain tabs'''.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

[[File:interface_tab2.png]]

==== wrap lines longer than 100-120 characters ====
'''Why:''' readability. Prior experience tells that old-school 80-columns margin just doesn't work with descriptive naming of variables and functions (i.e. descriptive == heavily wrapped). On the other hand, avoid making a readable, 200-characters long line even if it fits your monitor. Use good judgement.

==== consider using indentation/alignment for function arguments ====
'''Why:''' the purpose is twofold. On one hand it allows to pack a lot of arguments and expressions into a single function call without losing track of what is being done and no temporary variables:
<pre>
usePreparedUpdateBlade
(
'Port',
array
(
'name' => $port_name,
'type' => $port_type_id,
'label' => $port_label,
'reservation_comment' => $reservation_comment,
'l2address' => nullEmptyStr ($db_l2address),
),
array
(
'id' => $port_id,
'object_id' => $object_id
)
);
</pre>
On the other hand, it allows to group function arguments add/or add comments to them:
<pre>
function get8021QSyncOptions
(
$vswitch,
$D, // desired config
$C, // cached config
$R // running-config
)
{
$default_port = array
(
'mode' => 'access',
'allowed' => array (VLAN_DFL_ID),
'native' => VLAN_DFL_ID,
);
$ret = array();
</pre>
Use good judgement.

==== consider using indentation/alignment for arrays ====
'''Why:''' due to a few reasons. First, multiline array assignment/initialization can accommodate a notable amount of supplementary expressions:
<pre>
$ret[$pn] = array
(
'status' => 'martian_conflict',
'left' => array_key_exists ($pn, $C) ? $C[$pn] : array ('mode' => 'none'),
'right' => array_key_exists ($pn, $R) ? $R[$pn] : array ('mode' => 'none'),
);
</pre>
Second, updates to arrays that serve as lists produce cleaner diffs, for example:
<pre>
--- a/wwwroot/inc/remote.php
+++ b/wwwroot/inc/remote.php
@@ -64,6 +64,7 @@ $breedfunc = array
'jun10-get8021q-main' => 'jun10Read8021QConfig',
'jun10-xlatepushq-main' => 'jun10TranslatePushQueue',
'jun10-getallconf-main' => 'jun10SpotConfigText',
+ 'jun10-getlldpstatus-main' => 'jun10ReadLLDPStatus',
'ftos8-xlatepushq-main' => 'ftos8TranslatePushQueue',
'ftos8-getlldpstatus-main' => 'ftos8ReadLLDPStatus',
'ftos8-getmaclist-main' => 'ftos8ReadMacList',
</pre>
Finally, it makes tree-like array initialization more transparent:
<pre>
$SQLSchema = array
(
'object' => array
(
'table' => 'RackObject',
'columns' => array
(
'id' => 'id',
'name' => 'name',
'label' => 'label',
'asset_no' => 'asset_no',
'objtype_id' => 'objtype_id',
'rack_id' => '(SELECT MIN(rack_id) FROM RackSpace WHERE object_id = RackObject.id)',
'rack_id_2' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'rack')",
'container_id' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'object')",
'container_name' => '(SELECT name FROM RackObject WHERE id = container_id)',
'container_objtype_id' => '(SELECT objtype_id FROM RackObject WHERE id = container_id)',
'has_problems' => 'has_problems',
'comment' => 'comment',
'nports' => '(SELECT COUNT(*) FROM Port WHERE object_id = RackObject.id)',
'8021q_domain_id' => '(SELECT domain_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
'8021q_template_id' => '(SELECT template_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
),
'keycolumn' => 'id',
'ordcolumns' => array ('RackObject.name'),
),
</pre>

==== put <tt>else</tt> near its <tt>if</tt> ====
When an <tt>if</tt> operator includes the <tt>else</tt> part, consider arranging the branches so that the short branch belongs to the <tt>if</tt> and the long branch belongs to the <tt>else</tt>. '''Why:''' it helps following the code.

Holub, Allen (1995). Enough Rope to Shoot Yourself in the Foot. McGraw-Hill. ISBN 978-0-07-029689-3
"Section 57: Put the shortest clause of an <tt>if/else</tt> on top."

==== use the [http://en.wikipedia.org/wiki/%3F: conditional ternary operator] where it makes sense ====
'''Why:''' to use the language element in making the code look closer to what the code is intended to do. First, don't reinvent the conditional ternary operator with <tt>if</tt> like this:
<pre>
if ($row !== FALSE)
return $row[0];
else
return NULL;
</pre>
That block of code returns a value in either case, exactly one <tt>return</tt> would do the job:
<pre>
return $row === FALSE ? NULL : $row[0];
</pre>

Second, don't nest ternary conditionals, it is hard to read:
<pre>
$ret = ($ret > 0 ? 1 : ($ret < 0 ? -1 : 0));
</pre>
For that specific case use <tt>numSign()</tt>.

Finally, when a standalone ternary conditional isn't sufficient or is long/difficult to read, use temporary variables or necessary amount of <tt>if</tt>'s.

==== things to consider when adding a new function ====
* First, is it possible to use one of the existing functions or a combination of these?
* Carefully decide which file the function should be in (depends on its purpose and relation to other functions).
* Consider [http://en.wikipedia.org/wiki/CamelCase headlessCamelCase] for the function name.
* Try to keep functions focused, that is, small, doing just one thing but doing it very well.
* When adding a new function, add unit test(s) for it as well.

==== put <tt>$self = __FUNCTION__;</tt> at the beginning of a recursive function ====
'''Why:''' to make it easier to see a recursive function. Such a function should call itself as <tt>$self(...)</tt> so that if the function is renamed later its code requires no changes to work.
<pre>
# Return a list consisting of tag ID of the given tree node and IDs of all
# nodes it contains.
function getTagIDListForNode ($treenode)
{
$self = __FUNCTION__;
$ret = array ($treenode['id']);
foreach ($treenode['kids'] as $item)
$ret = array_merge ($ret, $self ($item));
return $ret;
}
</pre>

==== prefer <tt>//</tt> over <tt>#</tt> for single-line comments ====
'''Why:''' it saves keystokes (double-press one key versus pressing two different keys simultaneously). However, when adding a comment to a code that already uses <tt>#</tt>, be consistent with what is already there.
Also, the code contains ~ 2000 of //-style lines versus ~450 of #-style.

==== don't use <tt>foreach()</tt> by reference ====
'''Why:''' this valid language construct has a side effect that complicates things. Consider the following code:
<pre>
$a = array (1 => 'a', 2 => 'b', 3 => 'c');
foreach ($a as &$tmp)
$tmp = $tmp . '_str';
</pre>
So far so good, but once you decide to reuse <tt>$tmp</tt> and assign a new value to it, you will [unexpectedly] modify the array (<tt>$tmp</tt> still holds the reference to the last element). [https://bugs.php.net/bug.php?id=37410 This thread] discusses the workings of this at length. The workaround would be to use <tt>unset ($tmp)</tt> after the foreach-by-reference, but the least-surprising solution is to iterate over array keys if you need to modify array elements and <tt>array_walk()</tt> is not sufficient:
<pre>
foreach (array_keys ($a) as $k)
$a[$k] = $a[$k] . '_str';
</pre>

==== use double-quotes for strings only when necessary ====
'''Why:''' it saves the time required to tell "just strings" from strings that embed expansions. Consider the following:
<pre>
$string1 = 'Single-quotes give a hint that this string is just a string.';
$string2 = "Double-quotes give a hint that this string not just _may_ contain " .
"expansions but it actually does: here are $var1 and ${var2}";
</pre>

==== use <tt>array_key_exists()</tt> instead of <tt>isset()</tt> to test a key in an array ====
'''Why:''' with <tt>isset()</tt> it is impossible to distinguish a missing element from a typo in the array name:
<pre>
$arr = array (1 => 'a', 2 => 'b');
if (array_key_exists (10, $arr)) # FALSE
echo 'OK';
if (array_key_exists (10, $ar)) # FALSE and a PHP warning (note the typo)
echo 'OK';
if (isset ($arr[10])) # FALSE
echo 'OK';
if (isset ($ar[10])) # FALSE and no warning
echo 'OK';
</pre>

==== keep the PHP code compatible with PHP 5.5 and 5.6 ====
'''Why:''' because some long-term supported distributions still support these versions, and that's what the users still use in production.

==== keep the PHP code compatible with PHP versions 7.x ====
'''Why:''' because newer PHP versions tend to deprecate functions and extensions, so you have to account for that.

==== use "&&" and "||", not "and" and "or" ====
'''Why:''' because (unlike, for instance, C++) those are not just alternative notations but quite different operators. From the [http://php.net/manual/en/language.operators.precedence.php PHP operator precedence table] it is possible to see that, for example, the following two lines of code work in a very different way:
<pre>
$c = $a or $b; // Evaluate $a and assign the value to $c. If $c was set to false, evaluate $b and discard the value.
$c = $a || $b; // Evaluate $a. If the value is true, set $c to true. Otherwise evaluate $b and assign the value to $c.
</pre>
Not everybody remembers about this difference and eventually interprets the code not as PHP actually executes it. As the gain of "and" and "or" in RackTables is negligible, the simplest solution is not to use them at all.

==== test for an empty string in the simplest way possible ====
Just compare with an empty string. Only use <tt>strlen()</tt> and <tt>mb_strlen()</tt> when those are really required, i.e. when it is necessary to know the exact length of a string or a multibyte string.
<pre>
if ($s == '') // OK
...
if ($s != '') // OK
...
if (strlen ($s)) // overkill
...
if (! strlen ($s)) // overkill
...
if (mb_strlen ($s)) // overkill
...
if (! mb_strlen ($s)) // overkill
...
</pre>

==== use uppercase for NULL, TRUE and FALSE ====
'''Why:''' because PHP documentation always spells it this way, so let's keep it readbale (PHP interpreter itself is case-insensitive in this regard).

== SQL code style guide ==
==== use uppercase for SQL keywords and wrap long lines ====
'''Why:''' readability
<pre>
$result = usePreparedSelectBlade
(
'SELECT FileLink.file_id, FileLink.id AS link_id, name, type, size, ctime, mtime, atime, comment ' .
'FROM FileLink LEFT JOIN File ON FileLink.file_id = File.id ' .
'WHERE FileLink.entity_type = ? AND FileLink.entity_id = ? ORDER BY name',
array ($entity_type, $entity_id)
);
</pre>

==== use SELECT with an explicit list of columns, don't use <tt>SELECT *</tt> ====
'''Why:''' this is very well explained in many sources, for instance, [http://stackoverflow.com/questions/3639861/why-is-select-considered-harmful here] and [http://use-the-index-luke.com/blog/2013-08/its-not-about-the-star-stupid here].

SourceCode

2020-05-09T18:20:14Z

Infrastation: use HTTPS in a hyperlink

== the source code repository==
RackTables project uses git as version control system for the source code ([https://github.com/RackTables/racktables GitHub], [https://code.racktables.org/ read-only mirror]). The repository includes the following notable branches:
;master
:The main development branch, that is, the default branch for all new changes.
;maintenance-0.21.x
:The maintenance branch for 0.21.x stable releases (see the roadmap).
;maintenance-0.20.x
;maintenance-0.19.x
;maintenance-0.18.x
;maintenance-0.17.x
;maintenance-0.16.x
:Archived maintenance branches, which do not accept any new changes.

Use the following commands to get a working copy of the repository:
<pre>
# from the RackTables project repository
git clone git://github.com/RackTables/racktables.git
# or
git clone https://github.com/RackTables/racktables.git
# or
git clone ssh://git@github.com:RackTables/racktables.git

# from a GitHub fork (of your own or not)
git clone git://github.com/username/racktables.git
# or
git clone https://github.com/username/racktables.git
# or
git clone ssh://git@github.com:username/racktables.git
</pre>
Note that the first two schemas (<tt>git://</tt> and <tt>https://</tt>) are always '''read-only''' and the third (<tt>ssh://</tt>) may be '''read-only or read-write'''.

Use the following commands to examine local unsaved changes:
<pre>
git status
git diff
</pre>

The recommended way of contributing the work is to:
# fork RackTables on GitHub,
# push finished commits to the fork, and
# create a pull request.

In the case of a private repository use a [http://git-scm.com/docs/git-format-patch git format-patch] command to produce a patch and send it to the developers. When sending a patch, please make sure your branch is [http://git-scm.com/book/en/Git-Branching-Rebasing rebased] onto the latest respective (master or maintenance) branch.

== PHP code style guide ==
Almost all PHP source code in RackTables is original and the following style guide applies:
==== use [http://en.wikipedia.org/wiki/Indent_style#Allman_style Allman] indent style. ====
'''Why:''' Allman style is very diff-friendly when it comes to control structures. In Allman style expansion of a single inner operator into a larger code block (and vice versa) leaves both the inner (controlled) and the outer (controlling) operator intact:
<pre>
for ($i = 0; $i < 10; $i++)
+{
doSomething ($i);
+ doSomethingElse();
+}
</pre>
This works seamlessly at any indentation level and for all control structures (<tt>if/for/foreach/while</tt>), however deeply nested in each other. With careful indentation of <tt>case</tt> within <tt>switch</tt> it will work same well:
<pre>
switch ($var)
{
case 1:
doSomething();
break;
case 2:
- {
- doSomethingElse();
return 3;
- }
case 3:
+ {
+ doSomethingCompletelyDifferent();
return 4;
+ }
}
</pre>
Being diff-friendly means being friendly to a version control system (Subversion in the past, git at present). Neither the VCS nor the Allman style alone guarantee one's commits to be focused and clean. However, Allman style encourages commits that change only the lines that really need to be changed.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

==== use exactly one tab per indentation level ====
'''Why:''' different people prefer different (2, 4, 8...) amount of "spaces" per indentation level. Some projects use space indentation and force everyone to hit Space (Backspace) N times each time the developer needs to indent (unindent), regardless of their own preferred value of N. RackTables makes use of Tab and enables every developer to configure their editor for their preferred "tab width" (the screenshot below stands for tab width 2). Note that the tab width must stand for the amount of spaces the editor ''displays'', but not ''generates instead of'', that is, in the source file '''tabs must remain tabs'''.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

[[File:interface_tab2.png]]

==== wrap lines longer than 100-120 characters ====
'''Why:''' readability. Prior experience tells that old-school 80-columns margin just doesn't work with descriptive naming of variables and functions (i.e. descriptive == heavily wrapped). On the other hand, avoid making a readable, 200-characters long line even if it fits your monitor. Use good judgement.

==== consider using indentation/alignment for function arguments ====
'''Why:''' the purpose is twofold. On one hand it allows to pack a lot of arguments and expressions into a single function call without losing track of what is being done and no temporary variables:
<pre>
usePreparedUpdateBlade
(
'Port',
array
(
'name' => $port_name,
'type' => $port_type_id,
'label' => $port_label,
'reservation_comment' => $reservation_comment,
'l2address' => nullEmptyStr ($db_l2address),
),
array
(
'id' => $port_id,
'object_id' => $object_id
)
);
</pre>
On the other hand, it allows to group function arguments add/or add comments to them:
<pre>
function get8021QSyncOptions
(
$vswitch,
$D, // desired config
$C, // cached config
$R // running-config
)
{
$default_port = array
(
'mode' => 'access',
'allowed' => array (VLAN_DFL_ID),
'native' => VLAN_DFL_ID,
);
$ret = array();
</pre>
Use good judgement.

==== consider using indentation/alignment for arrays ====
'''Why:''' due to a few reasons. First, multiline array assignment/initialization can accommodate a notable amount of supplementary expressions:
<pre>
$ret[$pn] = array
(
'status' => 'martian_conflict',
'left' => array_key_exists ($pn, $C) ? $C[$pn] : array ('mode' => 'none'),
'right' => array_key_exists ($pn, $R) ? $R[$pn] : array ('mode' => 'none'),
);
</pre>
Second, updates to arrays that serve as lists produce cleaner diffs, for example:
<pre>
--- a/wwwroot/inc/remote.php
+++ b/wwwroot/inc/remote.php
@@ -64,6 +64,7 @@ $breedfunc = array
'jun10-get8021q-main' => 'jun10Read8021QConfig',
'jun10-xlatepushq-main' => 'jun10TranslatePushQueue',
'jun10-getallconf-main' => 'jun10SpotConfigText',
+ 'jun10-getlldpstatus-main' => 'jun10ReadLLDPStatus',
'ftos8-xlatepushq-main' => 'ftos8TranslatePushQueue',
'ftos8-getlldpstatus-main' => 'ftos8ReadLLDPStatus',
'ftos8-getmaclist-main' => 'ftos8ReadMacList',
</pre>
Finally, it makes tree-like array initialization more transparent:
<pre>
$SQLSchema = array
(
'object' => array
(
'table' => 'RackObject',
'columns' => array
(
'id' => 'id',
'name' => 'name',
'label' => 'label',
'asset_no' => 'asset_no',
'objtype_id' => 'objtype_id',
'rack_id' => '(SELECT MIN(rack_id) FROM RackSpace WHERE object_id = RackObject.id)',
'rack_id_2' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'rack')",
'container_id' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'object')",
'container_name' => '(SELECT name FROM RackObject WHERE id = container_id)',
'container_objtype_id' => '(SELECT objtype_id FROM RackObject WHERE id = container_id)',
'has_problems' => 'has_problems',
'comment' => 'comment',
'nports' => '(SELECT COUNT(*) FROM Port WHERE object_id = RackObject.id)',
'8021q_domain_id' => '(SELECT domain_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
'8021q_template_id' => '(SELECT template_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
),
'keycolumn' => 'id',
'ordcolumns' => array ('RackObject.name'),
),
</pre>

==== put <tt>else</tt> near its <tt>if</tt> ====
When an <tt>if</tt> operator includes the <tt>else</tt> part, consider arranging the branches so that the short branch belongs to the <tt>if</tt> and the long branch belongs to the <tt>else</tt>. '''Why:''' it helps following the code.

Holub, Allen (1995). Enough Rope to Shoot Yourself in the Foot. McGraw-Hill. ISBN 978-0-07-029689-3
"Section 57: Put the shortest clause of an <tt>if/else</tt> on top."

==== make conscise use of the [http://en.wikipedia.org/wiki/%3F: conditional ternary operator] ====
'''Why:''' to use the language element in making the code look closer to what the code is intended to do. First, don't reinvent the conditional ternary operator with <tt>if</tt> like this:
<pre>
if ($row !== FALSE)
return $row[0];
else
return NULL;
</pre>
That block of code returns a value in either case, exactly one <tt>return</tt> would do the job:
<pre>
return $row === FALSE ? NULL : $row[0];
</pre>

Second, don't nest ternary conditionals, it is hard to read:
<pre>
$ret = ($ret > 0 ? 1 : ($ret < 0 ? -1 : 0));
</pre>
For that specific case use <tt>numSign()</tt>.

Finally, when a standalone ternary conditional isn't sufficient or is long/difficult to read, use temporary variables or necessary amount of <tt>if</tt>'s.

==== things to consider when adding a new function ====
* First, is it possible to use one of the existing functions or a combination of these?
* Carefully decide which file the function should be in (depends on its purpose and relation to other functions).
* Consider [http://en.wikipedia.org/wiki/CamelCase headlessCamelCase] for the function name.
* Try to keep functions focused, that is, small, doing just one thing but doing it very well.
* When adding a new function, add unit test(s) for it as well.

==== put <tt>$self = __FUNCTION__;</tt> at the beginning of a recursive function ====
'''Why:''' to make it easier to see a recursive function. Such a function should call itself as <tt>$self(...)</tt> so that if the function is renamed later its code requires no changes to work.
<pre>
# Return a list consisting of tag ID of the given tree node and IDs of all
# nodes it contains.
function getTagIDListForNode ($treenode)
{
$self = __FUNCTION__;
$ret = array ($treenode['id']);
foreach ($treenode['kids'] as $item)
$ret = array_merge ($ret, $self ($item));
return $ret;
}
</pre>

==== prefer <tt>//</tt> over <tt>#</tt> for single-line comments ====
'''Why:''' it saves keystokes (double-press one key versus pressing two different keys simultaneously). However, when adding a comment to a code that already uses <tt>#</tt>, be consistent with what is already there.
Also, the code contains ~ 2000 of //-style lines versus ~450 of #-style.

==== don't use <tt>foreach()</tt> by reference ====
'''Why:''' this valid language construct has a side effect that complicates things. Consider the following code:
<pre>
$a = array (1 => 'a', 2 => 'b', 3 => 'c');
foreach ($a as &$tmp)
$tmp = $tmp . '_str';
</pre>
So far so good, but once you decide to reuse <tt>$tmp</tt> and assign a new value to it, you will [unexpectedly] modify the array (<tt>$tmp</tt> still holds the reference to the last element). [https://bugs.php.net/bug.php?id=37410 This thread] discusses the workings of this at length. The workaround would be to use <tt>unset ($tmp)</tt> after the foreach-by-reference, but the least-surprising solution is to iterate over array keys if you need to modify array elements and <tt>array_walk()</tt> is not sufficient:
<pre>
foreach (array_keys ($a) as $k)
$a[$k] = $a[$k] . '_str';
</pre>

==== use double-quotes for strings only when necessary ====
'''Why:''' it saves the time required to tell "just strings" from strings that embed expansions. Consider the following:
<pre>
$string1 = 'Single-quotes give a hint that this string is just a string.';
$string2 = "Double-quotes give a hint that this string not just _may_ contain " .
"expansions but it actually does: here are $var1 and ${var2}";
</pre>

==== use <tt>array_key_exists()</tt> instead of <tt>isset()</tt> to test a key in an array ====
'''Why:''' with <tt>isset()</tt> it is impossible to distinguish a missing element from a typo in the array name:
<pre>
$arr = array (1 => 'a', 2 => 'b');
if (array_key_exists (10, $arr)) # FALSE
echo 'OK';
if (array_key_exists (10, $ar)) # FALSE and a PHP warning (note the typo)
echo 'OK';
if (isset ($arr[10])) # FALSE
echo 'OK';
if (isset ($ar[10])) # FALSE and no warning
echo 'OK';
</pre>

==== keep the PHP code compatible with PHP 5.5 and 5.6 ====
'''Why:''' because some long-term supported distributions still support these versions, and that's what the users still use in production.

==== keep the PHP code compatible with PHP versions 7.x ====
'''Why:''' because newer PHP versions tend to deprecate functions and extensions, so you have to account for that.

==== use "&&" and "||", not "and" and "or" ====
'''Why:''' because (unlike, for instance, C++) those are not just alternative notations but quite different operators. From the [http://php.net/manual/en/language.operators.precedence.php PHP operator precedence table] it is possible to see that, for example, the following two lines of code work in a very different way:
<pre>
$c = $a or $b; // Evaluate $a and assign the value to $c. If $c was set to false, evaluate $b and discard the value.
$c = $a || $b; // Evaluate $a. If the value is true, set $c to true. Otherwise evaluate $b and assign the value to $c.
</pre>
Not everybody remembers about this difference and eventually interprets the code not as PHP actually executes it. As the gain of "and" and "or" in RackTables is negligible, the simplest solution is not to use them at all.

==== test for an empty string in the simplest way possible ====
Just compare with an empty string. Only use <tt>strlen()</tt> and <tt>mb_strlen()</tt> when those are really required, i.e. when it is necessary to know the exact length of a string or a multibyte string.
<pre>
if ($s == '') // OK
...
if ($s != '') // OK
...
if (strlen ($s)) // overkill
...
if (! strlen ($s)) // overkill
...
if (mb_strlen ($s)) // overkill
...
if (! mb_strlen ($s)) // overkill
...
</pre>

==== use uppercase for NULL, TRUE and FALSE ====
'''Why:''' because PHP documentation always spells it this way, so let's keep it readbale (PHP interpreter itself is case-insensitive in this regard).

== SQL code style guide ==
==== use uppercase for SQL keywords and wrap long lines ====
'''Why:''' readability
<pre>
$result = usePreparedSelectBlade
(
'SELECT FileLink.file_id, FileLink.id AS link_id, name, type, size, ctime, mtime, atime, comment ' .
'FROM FileLink LEFT JOIN File ON FileLink.file_id = File.id ' .
'WHERE FileLink.entity_type = ? AND FileLink.entity_id = ? ORDER BY name',
array ($entity_type, $entity_id)
);
</pre>

==== use SELECT with an explicit list of columns, don't use <tt>SELECT *</tt> ====
'''Why:''' this is very well explained in many sources, for instance, [http://stackoverflow.com/questions/3639861/why-is-select-considered-harmful here] and [http://use-the-index-luke.com/blog/2013-08/its-not-about-the-star-stupid here].

RackTablesDevelGuide

2020-04-17T18:50:33Z

Infrastation: use the current roadmap

[[File:RackTables-development-roadmap-2019Q4.png|311px|thumb|right]]
= Config options =
Variables are stored in the Config SQL table:
<pre>
mysql> DESCRIBE Config;
+----------------+-----------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+----------------+-----------------------+------+-----+---------+-------+
| varname | char(32) | NO | PRI | NULL | |
| varvalue | char(255) | NO | | NULL | |
| vartype | enum('string','uint') | NO | | string | |
| emptyok | enum('yes','no') | NO | | no | |
| is_hidden | enum('yes','no') | NO | | yes | |
| is_userdefined | enum('yes','no') | NO | | no | |
| description | text | YES | | NULL | |
+----------------+-----------------------+------+-----+---------+-------+
7 rows in set (0.00 sec)
</pre>
Options are read and written with getConfigVar() and setConfigVar() functions respectively. The current naming convention for new options is to use descriptive expressions in ALL_CAPITAL_LETTERS with spaces REPLACED_WITH_UNDERSCORES. When adding a new option, check the following places:
# upgrade.php
# install/init-dictbase.sql
# inc/ophandlers.php:resetUIConfig()
Default values must match regardless of the way they were set: initial setup, upgrade or UI reset.

= Exceptions and error handling =
Error handling now can be done by exceptions mechanism. index.php and process.php have been wrapped in
<pre>
ob_start();
try{
...
ob_end_flush();
} catch {
print_error_nicely();
}
</pre>
kind of code, so every exception you miss and not catch will be printed instead of the page that had to be printed.

This saves a lot of code, take a look at a function
<pre>
// before

function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '')
{
if ($chapter_no <= 0)
{
showError ('Invalid args', __FUNCTION__);
die;
}
global $dbxlink;
$query =
"update Dictionary set dict_value = '${dict_value}' where chapter_id=${chapter_no} " .
"and dict_key=${dict_key} limit 1";
$result = $dbxlink->query ($query);
if ($result == NULL)
{
showError ('SQL query failed', __FUNCTION__);
die;
}
return TRUE;
}

// and after

function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '')
{
if ($chapter_no <= 0)
throw InvalidArgException('$chapter_no', $chapter_no);
// the function below does not exist
Database::updateWhere(array('dict_value'=>$dict_value), 'Dictionary', array('chapter_id'=>$chapter_no, 'dict_key'=>$dict_key));
return TRUE;
}
</pre>

Function Database::updateWhere throws an exception if query is bad, and you can catch it if you want and handle it as necessary, or you can just ignore it and application will display error message with a stacktrace and such.

Exceptions registered so far:

;RackTablesError
:Fatal, final error, usually annotated.

;RTDatabaseError
:"Soft" database error (UNIQUE/FOREIGN KEY constraint violation or timeout).

;RTGatewayError
:An external gateway raised an error or the data it returned was corrupt or otherwise invalid.

;EntityNotFoundException
:Requested record could not be found in the database.

;InvalidArgException
:At least one of the arguments provided to a function had invalid value, and that value did NOT come from user's input. This means a programming error and cannot be worked around.

;InvalidRequestArgException
:Ditto, but the value was supplied by the user, and the error should be handled with an "inline" error message.

;RTBuildLVSConfigError
:LVS keepalived text compilation failed.
----

= RackCode =
<pre>
# identifier
ID ::= ^[[:alnum:]]([\. _~-]?[[:alnum:]])*$
# identifier in brackets
PREDICATE ::= [ID]
DEFINE ::= define PREDICATE
# identifier in curly braces
TAG ::= {ID}
# identifier in curly braces, starting with dollar sign
AUTOTAG ::= {$ID}
# context modifier
CTXMOD ::= clear | insert TAG | remove TAG
# context modifier list
CTXMODLIST ::= CTXMODLIST CTXMOD | CTXMOD
UNARY_EXPRESSION ::= true | false | TAG | AUTOTAG | PREDICATE | (EXPRESSION) | not UNARY_EXPRESSION
# logical AND
AND_EXPRESSION ::= AND_EXPRESSION and UNARY_EXPRESSION | UNARY_EXPRESSION
# logical OR
EXPRESSION ::= EXPRESSION or AND_EXPRESSION | AND_EXPRESSION
GRANT ::= allow EXPRESSION | deny EXPRESSION
DEFINITION ::= DEFINE EXPRESSION
ADJUSTMENT ::= context CTXMODLIST on EXPRESSION
# RackCode permission text
CODETEXT ::= CODETEXT GRANT | CODETEXT DEFINITION | CODETEXT ADJUSTMENT | GRANT | DEFINITION | ADJUSTMENT
</pre>
Comments in RackCode last from the first <tt>#</tt> character to the end of current line and are filtered out automatically:
<pre>
allow {tech support} # or {admins} <--- note where comment starts
and {assets} # <--- this is still a part of "allow" statement

deny {guests}
</pre>

= API =
== Hello, World! ==
To enable all RackTables functions and load all necessary system data, it is enough to include one file.
<pre>
<?php

include ('inc/init.php');
// do something

?>
</pre>

There is a special parameter, which tells, if current file is intended to be run by web-server or from a command line. In the latter case neither authentication nor authorization is performed.
<pre>
<?php

$script_mode = TRUE;
include ('inc/init.php');

echo "I am a crontab script!\n";
// do something

?>
</pre>

== Searching for the appropriate library function ==
The easy way to determine which function does what you need to is analyze how the corresponding web interface request is processed.

Each modification through web causes HTTP POST request being sent with at least these base parameters: 'page', 'tab', 'op'.
There is the $ophandler array in wwwroot/inc/navigation.php filled with function names for each triplet of base web operation parameters.

Then, when you determine the handler function name for you operation (like object creating), you could examine its code in wwwroot/inc/ophandlers.php. It usually calls appropriate functions from database.php.

Also, there are some trivial operations which have no special ophandler function. Then the universal database wrapper called tableHandler takes place. It makes direct SQL queries, building them by $opspec_list array data.

== Realms ==
There are several principal realms in !RackTables database. Any realm contains zero, one or more records. Each such record is addressed by its ID (primary key).

;object
:All servers, switches, UPSes, wireless, cable management and any other stuff, which is viewed and managed on the main "Objects" page.
;ipv4net
:all IPv4 networks
;ipv6net
:all IPv6 networks
;user
:All local accounts. There is at least one local account in any RackTables system (admin). There may be more.
;rack
:All racks.
;file
:All files.
;ipv4vs
:All IPv4 virtual services.
;ipv4rspool
:All IPv4 real server pools.

== function scanRealmByText ($realm, $ftext = "") ==
;realm
:String equal to one of the realms shown above.
;ftext
:Optional filter text. If this text is empty, all records of the realm are returned. If it is not empty, it is interpreted as a !RackCode expression. This expression is then evaluated against each record of the realm and only those records, for which the filter returned TRUE, are returned.

<pre>
<?php

include ('inc/init.php');

$allusers = scanRealmByText ('user');
$smallnetworks = scanRealmByText ('ipv4net', '{small network}');
$unmounted_objects = scanRealmByText ('object', '{$unmounted}');

?>
</pre>

== function spotEntity ($realm, $id) ==
This is the right function to get information about some record, for which you know where it belongs to and what its key value is. If this information isn't available, it has to be discovered somehow first.

;realm
:Realm name.
;id
:Record number (key value, ID...).

<pre>
<?php

include ('inc/init.php');

$adminuser = spotEntity ('user', 1); // Admin account is always number 1.
$myspecialfile = spotEntity ('file', 12345);
$serverinfo = spotEntity ('object', 67890);

?>
</pre>

== function amplifyCell (&$record, $dummy = NULL) ==
It is assumed, that spotEntity() loads only basic data about the record requested. "Basic" means enough for renderCell() to do its job or to render a row in a table. To get detailed information about the "cell" it is necessary to execute amplifyCell() on it:
<pre>
<?php
include ('inc/init.php');

$adminuser = spotEntity ('user', 1); // Admin account is always number 1.
amplifyCell ($adminuser);

$unmounted_objects = scanRealmByText ('object', '{$unmounted}');
array_walk ($unmounted_objects, 'amplifyCell');
?>
</pre>

== function renderCell ($cell) ==
Render cell structure as a rectangular block with icon, name, tags and other information. Available since 0.17.2.

= Dictionary =
== Where the data is ==
Since release 0.17.2 all records are stored in file <tt>inc/dictionary.php</tt>:
<pre>
$dictionary = array
(
1 => array ('chapter_id' => 1, 'dict_value' => 'BlackBox'),
2 => array ('chapter_id' => 1, 'dict_value' => 'PDU'),
3 => array ('chapter_id' => 1, 'dict_value' => 'Shelf'),
4 => array ('chapter_id' => 1, 'dict_value' => 'Server'),
5 => array ('chapter_id' => 1, 'dict_value' => 'DiskArray'),
6 => array ('chapter_id' => 1, 'dict_value' => 'TapeLibrary'),
7 => array ('chapter_id' => 1, 'dict_value' => 'Router'),
8 => array ('chapter_id' => 1, 'dict_value' => 'Network switch'),
9 => array ('chapter_id' => 1, 'dict_value' => 'PatchPanel'),
10 => array ('chapter_id' => 1, 'dict_value' => 'CableOrganizer'),
11 => array ('chapter_id' => 1, 'dict_value' => 'spacer'),
12 => array ('chapter_id' => 1, 'dict_value' => 'UPS'),
[...]
</pre>

== meaning of chapter ID ==
<pre>
mysql> SELECT * FROM Chapter;
+----+--------+-----------------------------+
| id | sticky | name |
+----+--------+-----------------------------+
| 1 | yes | RackObjectType |
| 2 | yes | PortType |
| 11 | no | server models |
| 12 | no | network switch models |
| 13 | no | server OS type |
| 14 | no | switch OS type |
| 16 | no | router OS type |
| 17 | no | router models |
| 18 | no | disk array models |
| 19 | no | tape library models |
| 21 | no | KVM switch models |
| 22 | no | multiplexer models |
| 23 | no | console models |
| 24 | no | network security models |
| 25 | no | wireless models |
| 26 | no | fibre channel switch models |
| 27 | no | PDU models |
+----+--------+-----------------------------+
17 rows in set (0.00 sec)
</pre>

== wikilinks ==
It is possible to render a record as an URL:
<pre>[[ something | http://somewhere/ ]]</pre>
However, it is up to the editor, if to include URL into description or not. URLs can be added, changed and removed from particular records later, if it makes sense.

== G-markers ==
Text before the marker is always used for OPTGROUP in SELECT element. The difference is in the way the text is rendered as a plain text or a clickable URL. GSKIP makes OPTGROUP name to be skipped. GPASS passes OPTGROUP name on the text:
<pre>
719 => array ('chapter_id' => 24, 'dict_value' => '[[Cisco%GPASS%ASR 1006 | http://cisco.com/en/US/products/ps9438/index.html]]'),
720 => array ('chapter_id' => 13, 'dict_value' => '[[BSD%GSKIP%OpenBSD 3.3 | http://openbsd.org/33.html]]'),
</pre>

[[Image:dictionary-G-markers.png]]

== How to pick dictionary changes up between the releases ==
This is sometimes needed to keep git working copies up to date. There is no GUI for this to avoid confusion to the users of normal releases.
<pre>
<?php

$script_mode = TRUE;
require_once '/path/to/racktables/wwwroot/inc/init.php';
require_once '/path/to/racktables/wwwroot/inc/dictionary.php';
require_once '/path/to/racktables/wwwroot/inc/upgrade.php';

executeUpgradeBatch ('dictionary');

?>
</pre>

= Customizing =
== Overriding the search procedure ==

RackTables contains API allowing to customize search. Two ways of customizing
are available:

a) You could change text request (search terms) before passing it to standard search procedure;

b) You could either modify the search results list returned by the standard search procedure, or fill that list completely by yourself.

Of course, you can combine the methods above.

First, you need Racktables to include your code. Racktables tries to include
the user's php lib called "wwwroot/inc/local.php". To be honest, the actual
include path is "$path_to_local_php", which by default equals to
"$racktables_confdir . '/local.php'". $racktables_confdir, consequently, by default
is the dir where the library files are stored (wwwroot/inc). You could override
either of these paths by making separate entry point (custom index.php), or in
secret.php. If you want to actively use plugin model, you may want to write a
generic local.php scanning your custom plugins directory and including files from
it. This technique will allow you install plugins by simply putting them into this dir,
and to easily exchange plugins with the community.

So, you've decided to store your local.php in the default location and override
the search procedure. Lets take an example. We want to take a URL in search box,
extract hostname from it, resolve it into an IP address and than display the search
results for this address. Proper local.php is below:
<pre>
<?php
//step 1
$page['search']['handler'] = 'searchHandler_Local';

function searchHandler_Local ()
{
// step 2
$terms = trim ($_REQUEST['q']);

// step 3
if (preg_match("/^(http:\/\/)/", $terms))
{ // Search by IP if URL was given
preg_match("/^(http:\/\/)?([^\/]+)/i", $terms, $matches);
$terms = gethostbyname($matches[2]);
}

// step 4
$results = searchEntitiesByText ($terms);

// step 5
// modify the $results you need to

// step 6
renderSearchResults ($terms, $results);
}

?>
</pre>

Let's describe this simple script step-by step.

Step 1. First we overwrite the search handler procedure name, replacing the standard one
by the custom 'searchHandler_Local'. Please note that you can not chain overrides -
as soon you set procedure name in $page['search']['handler'] (as well as any other
handler) the old handler is forgotten, and the new one is responsible for calling it,
if it decides to.

Step 2. We need to retrieve the search request. It is passed in 'q' HTTP GET parameter to
the search handler.

Step 3. We rewrite the search request text replacing URL to the corresponding IP address.
It is an example of using the way (a) of customizing RackTables search (see above)

Step 4. Let the standard search procedure do its job. We call searchEntitiesByText for that.

Step 5. Here you could change the results returned by standard function. This array structure
is pretty complex, you may want to examine it by calling var_dump. The array is indexed by
search method (like 'object' or 'ipv6addressbydescr'). The rest structure depends of the first
key value. If you want to display your very own search results section, you could add the unknown
key into this array which will be used as a header for this results section. The HTML code for its
body will be the value of $results by the given key.

Step 6. Display the search results using renderSearchResults standard function.

== Adding a custom report ==
There is a simple way to write custom reports and embed them into the RackTables user interface.

All you need to do is write a report rendering function, apparently using such RackTables API functions
like scanRealmByText, spotEntity and renderCell, and register this function as a report rendering handler.
This example should make it clear:

1. Save the code below into the plugins/test-report.php file:
<pre>
<?php

$tabhandler['reports']['test'] = 'renderTestReport'; // register a report rendering function
$tab['reports']['test'] = 'Test Report'; // title of the report tab

function renderTestReport()
{
// fill the HW type stat array
$stat = array();
$total = 0;
$filter = '{switch} and {Moscow}';
foreach (scanRealmByText ('object', $filter) as $switch)
{
$attributes = getAttrValues ($switch['id']);
if (isset ($attributes[2]))
{
$attr = $attributes[2];
if (! isset ($stat[$attr['key']]))
$stat[$attr['key']] = array
(
'value' => $attr['a_value'],
'count' => 0,
);
++$stat[$attr['key']]['count'];
++$total;
}
}

// display the stat array
echo "<h2>Moscow switches HW types report ($total)</h2><ul>";
foreach ($stat as $type_id => $type)
{
$type_filter = $filter . ' and {$attr_2_' . $type_id . '}';
$link = '<a href="' . makeHref (array ('page' => 'depot', 'cfe' => $type_filter)) . '">' . $type['count'] . ' devices</a>';
echo "<li>${type['value']} - $link</li>";
}
echo '</ul>';
}

?>
</pre>

2. To install your report into RackTables, place the file in the plugins directory.

This report displays switch devices located in Moscow, grouped by their hardware model types. Each line of output contains the device count of corresponding model and a link to view the device list, like this:
<pre>
Moscow switches HW types report (2)
* Cisco Catalyst 2960G-24PC - <a>1 devices</a>
* Cisco Catalyst 2960G-24TC - <a>1 devices</a>
</pre>

= 802.1Q internals =
== execution of "pull-only" and "pull+push" sync requests ==
[[Image:RackTables-8021Q-sync.png]]

= SNMP sync =
== Overview ==
The feature evolved as a procedure intended to be run once for any given device. The main procedure is built around the ifTable SNMP tree, which belongs to IF-MIB (very old and ubiquitous one). With regard to network switches, everything is done in the doSwitchSNMPmining() function, located in inc/snmp.php.

The device is polled using the FQDN (hostname or IP/IPv6) attribute, if set. If not, assigned IP addresses will be polled.

First, subsets of ifTable are taken and combined in a way to produce a PHP array of all interfaces (with MAC address info for each interface).

Then, for each item in the interface list, a "processor" is tried from the list of processors (which is known for each supported product number, that is, SNMP OID). This way, there is a list of "processor" items and a list of known switches, where each item uses one or more processors to process the list of interfaces. There is also a vendor-specific procedure for things like serial number or console port type.

Each processor is built as follows:
* 'pattern' stands for PCRE pattern, which is tried against interface name (ifDescr in SNMP).
* 'replacement' is a PCRE replacement for it (most often interface names need to be compressed into something of reasonable length, e.g. 'GigabitEthernet1/2/3' -> 'gi1/2/3').
* 'label' stands for port's visible label ('replacement' was for port's interface name, i.e. the one which switch's operating system uses) in SQL it is Port.label.
* 'dict_key' stands for a special value which can be defined in one of two forms: either "N2" or "N1-N2" (in the former case N1 is taken to be equal to 1).

N1 stands for IIF ID, its valid values are stored in the PortInnerInterface table.
N2 stands for OIF ID, its values are stored in Dictionary chapter 2.

For example, the most popular interface, "hardwired 1000Base-T" may be written as either 24 or '1-24'.
For an "empty XENPAK" port, use '5-1079'.
IIF stands for "Inner InterFace" and OIF stands for "Outer InterFace"
In the Port table, IIF ID is stored in the "iif_id" column and OIF ID in the "type" column.
this way the description of "dict_key" in a processor item

The 'known_switches' array is used to map processors and other information to specific switch models.
* 'dict_key' is the dictionary ID which represents the switch model. The list of known models is defined in dictionary.php.
* 'text' is a basic description of the device that is presented to the user after discovery is complete.
* 'processors' lists which processors are applied to the device.
* 'ifDescrOID' is an optional attribute used in cases where the SNMP ifDescr data does not include unique values (e.g. all interfaces are named 'Ethernet Interface'). It specifies the name of the table which does indeed contain unique interface names.
* 'try_next_proc' controls the way different processors are applied. It only refers to if the PCRE pattern has matched or not. In the case of TRUE, the port is created as prescribed and processing of the current interface goes on with the next processor item. In the case of FALSE, the port is added and no more processor items are tried for the current interface (procedure goes on to the next interface).

When it comes to adding support for another switch, the best route is to study the device to find out which physical ports it has and how they are represented in SNMP. In particular, 'try_next_proc' is used for combo ports (ones allowing either copper or SFP media under the same OS interface). The work is much easier when some other device from the same product line already exists in snmp.php. Some product lines only have different OIDs and dict_key values, while everything else is the same (e.g. a switch which has PoE ports and one which does not).

=== Environmental requirements ===
This function uses symbolic OIDs to access the devices which in turn requires base MIBs to be installed and configured properly. If they're not you'll get ''"Fatal SNMP error"'' on the webpage and ''"PHP Warning: snmp2_get(): Invalid object identifier: sysObjectID.0 in /var/www/rt/inc/snmp.php"'' in the webserver error log.

In case of ''Debian GNU/Linux'' (squeeze and up), for example, this means that apart from <tt>php5-snmp</tt> there must be <tt>snmp-mibs-downloader</tt> installed, the MIBs downloaded and <tt>/etc/snmp/snmp.conf</tt> edited to allow their use. Do not forget to restart php (apache) after the changes.

== Example 1: Arista 7124S ==
This is a switch which has 24 SFP+ ports, two management ports and one power supply.

SNMP returns the following names for the ifDescr table:
* Ethernet1
* Ethernet2
* ...
* Ethernet24
* Management1
* Management2

Add to dictionary.php:
<pre>
1610 => array ('chapter_id' => 12, 'dict_value' => 'Arista%GPASS%7124S'),
</pre>

Add to snmp.php:
<pre>
$iftable_processors['arista-any-SFP+'] = array
(
'pattern' => '@^Ethernet([[:digit:]]+)$@',
'replacement' => '\\1',
'dict_key' => '9-1084',
'label' => '\\1',
'try_next_proc' => FALSE,
);

$iftable_processors['arista-management'] = array
(
'pattern' => '@^Management(1|2)$@',
'replacement' => 'mgmt\\1',
'dict_key' => '1-24',
'label' => 'Management',
'try_next_proc' => FALSE,
);
</pre>

<pre>
'30065.1.3011.7124.3282' => array
(
'dict_key' => 1610,
'text' => 'DCS-7124S: 24 SFP+/10000',
'processors' => array ('arista-any-SFP+', 'arista-management'),
),
</pre>

SourceCode

2019-12-07T20:48:22Z

Infrastation: /* the source code repository */ update the list of git branches

== the source code repository==
RackTables project uses git as version control system for the source code ([https://github.com/RackTables/racktables GitHub], [http://code.racktables.org/ read-only mirror]). The repository includes the following notable branches:
;master
:The main development branch, that is, the default branch for all new changes.
;maintenance-0.21.x
:The maintenance branch for 0.21.x stable releases (see the roadmap).
;maintenance-0.20.x
;maintenance-0.19.x
;maintenance-0.18.x
;maintenance-0.17.x
;maintenance-0.16.x
:Archived maintenance branches, which do not accept any new changes.

Use the following commands to get a working copy of the repository:
<pre>
# from the RackTables project repository
git clone git://github.com/RackTables/racktables.git
# or
git clone https://github.com/RackTables/racktables.git
# or
git clone ssh://git@github.com:RackTables/racktables.git

# from a GitHub fork (of your own or not)
git clone git://github.com/username/racktables.git
# or
git clone https://github.com/username/racktables.git
# or
git clone ssh://git@github.com:username/racktables.git
</pre>
Note that the first two schemas (<tt>git://</tt> and <tt>https://</tt>) are always '''read-only''' and the third (<tt>ssh://</tt>) may be '''read-only or read-write'''.

Use the following commands to examine local unsaved changes:
<pre>
git status
git diff
</pre>

The recommended way of contributing the work is to:
# fork RackTables on GitHub,
# push finished commits to the fork, and
# create a pull request.

In the case of a private repository use a [http://git-scm.com/docs/git-format-patch git format-patch] command to produce a patch and send it to the developers. When sending a patch, please make sure your branch is [http://git-scm.com/book/en/Git-Branching-Rebasing rebased] onto the latest respective (master or maintenance) branch.

== PHP code style guide ==
Almost all PHP source code in RackTables is original and the following style guide applies:
==== use [http://en.wikipedia.org/wiki/Indent_style#Allman_style Allman] indent style. ====
'''Why:''' Allman style is very diff-friendly when it comes to control structures. In Allman style expansion of a single inner operator into a larger code block (and vice versa) leaves both the inner (controlled) and the outer (controlling) operator intact:
<pre>
for ($i = 0; $i < 10; $i++)
+{
doSomething ($i);
+ doSomethingElse();
+}
</pre>
This works seamlessly at any indentation level and for all control structures (<tt>if/for/foreach/while</tt>), however deeply nested in each other. With careful indentation of <tt>case</tt> within <tt>switch</tt> it will work same well:
<pre>
switch ($var)
{
case 1:
doSomething();
break;
case 2:
- {
- doSomethingElse();
return 3;
- }
case 3:
+ {
+ doSomethingCompletelyDifferent();
return 4;
+ }
}
</pre>
Being diff-friendly means being friendly to a version control system (Subversion in the past, git at present). Neither the VCS nor the Allman style alone guarantee one's commits to be focused and clean. However, Allman style encourages commits that change only the lines that really need to be changed.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

==== use exactly one tab per indentation level ====
'''Why:''' different people prefer different (2, 4, 8...) amount of "spaces" per indentation level. Some projects use space indentation and force everyone to hit Space (Backspace) N times each time the developer needs to indent (unindent), regardless of their own preferred value of N. RackTables makes use of Tab and enables every developer to configure their editor for their preferred "tab width" (the screenshot below stands for tab width 2). Note that the tab width must stand for the amount of spaces the editor ''displays'', but not ''generates instead of'', that is, in the source file '''tabs must remain tabs'''.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

[[File:interface_tab2.png]]

==== wrap lines longer than 100-120 characters ====
'''Why:''' readability. Prior experience tells that old-school 80-columns margin just doesn't work with descriptive naming of variables and functions (i.e. descriptive == heavily wrapped). On the other hand, avoid making a readable, 200-characters long line even if it fits your monitor. Use good judgement.

==== consider using indentation/alignment for function arguments ====
'''Why:''' the purpose is twofold. On one hand it allows to pack a lot of arguments and expressions into a single function call without losing track of what is being done and no temporary variables:
<pre>
usePreparedUpdateBlade
(
'Port',
array
(
'name' => $port_name,
'type' => $port_type_id,
'label' => $port_label,
'reservation_comment' => $reservation_comment,
'l2address' => nullEmptyStr ($db_l2address),
),
array
(
'id' => $port_id,
'object_id' => $object_id
)
);
</pre>
On the other hand, it allows to group function arguments add/or add comments to them:
<pre>
function get8021QSyncOptions
(
$vswitch,
$D, // desired config
$C, // cached config
$R // running-config
)
{
$default_port = array
(
'mode' => 'access',
'allowed' => array (VLAN_DFL_ID),
'native' => VLAN_DFL_ID,
);
$ret = array();
</pre>
Use good judgement.

==== consider using indentation/alignment for arrays ====
'''Why:''' due to a few reasons. First, multiline array assignment/initialization can accommodate a notable amount of supplementary expressions:
<pre>
$ret[$pn] = array
(
'status' => 'martian_conflict',
'left' => array_key_exists ($pn, $C) ? $C[$pn] : array ('mode' => 'none'),
'right' => array_key_exists ($pn, $R) ? $R[$pn] : array ('mode' => 'none'),
);
</pre>
Second, updates to arrays that serve as lists produce cleaner diffs, for example:
<pre>
--- a/wwwroot/inc/remote.php
+++ b/wwwroot/inc/remote.php
@@ -64,6 +64,7 @@ $breedfunc = array
'jun10-get8021q-main' => 'jun10Read8021QConfig',
'jun10-xlatepushq-main' => 'jun10TranslatePushQueue',
'jun10-getallconf-main' => 'jun10SpotConfigText',
+ 'jun10-getlldpstatus-main' => 'jun10ReadLLDPStatus',
'ftos8-xlatepushq-main' => 'ftos8TranslatePushQueue',
'ftos8-getlldpstatus-main' => 'ftos8ReadLLDPStatus',
'ftos8-getmaclist-main' => 'ftos8ReadMacList',
</pre>
Finally, it makes tree-like array initialization more transparent:
<pre>
$SQLSchema = array
(
'object' => array
(
'table' => 'RackObject',
'columns' => array
(
'id' => 'id',
'name' => 'name',
'label' => 'label',
'asset_no' => 'asset_no',
'objtype_id' => 'objtype_id',
'rack_id' => '(SELECT MIN(rack_id) FROM RackSpace WHERE object_id = RackObject.id)',
'rack_id_2' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'rack')",
'container_id' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'object')",
'container_name' => '(SELECT name FROM RackObject WHERE id = container_id)',
'container_objtype_id' => '(SELECT objtype_id FROM RackObject WHERE id = container_id)',
'has_problems' => 'has_problems',
'comment' => 'comment',
'nports' => '(SELECT COUNT(*) FROM Port WHERE object_id = RackObject.id)',
'8021q_domain_id' => '(SELECT domain_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
'8021q_template_id' => '(SELECT template_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
),
'keycolumn' => 'id',
'ordcolumns' => array ('RackObject.name'),
),
</pre>

==== put <tt>else</tt> near its <tt>if</tt> ====
When an <tt>if</tt> operator includes the <tt>else</tt> part, consider arranging the branches so that the short branch belongs to the <tt>if</tt> and the long branch belongs to the <tt>else</tt>. '''Why:''' it helps following the code.

Holub, Allen (1995). Enough Rope to Shoot Yourself in the Foot. McGraw-Hill. ISBN 978-0-07-029689-3
"Section 57: Put the shortest clause of an <tt>if/else</tt> on top."

==== make conscise use of the [http://en.wikipedia.org/wiki/%3F: conditional ternary operator] ====
'''Why:''' to use the language element in making the code look closer to what the code is intended to do. First, don't reinvent the conditional ternary operator with <tt>if</tt> like this:
<pre>
if ($row !== FALSE)
return $row[0];
else
return NULL;
</pre>
That block of code returns a value in either case, exactly one <tt>return</tt> would do the job:
<pre>
return $row === FALSE ? NULL : $row[0];
</pre>

Second, don't nest ternary conditionals, it is hard to read:
<pre>
$ret = ($ret > 0 ? 1 : ($ret < 0 ? -1 : 0));
</pre>
For that specific case use <tt>numSign()</tt>.

Finally, when a standalone ternary conditional isn't sufficient or is long/difficult to read, use temporary variables or necessary amount of <tt>if</tt>'s.

==== things to consider when adding a new function ====
* First, is it possible to use one of the existing functions or a combination of these?
* Carefully decide which file the function should be in (depends on its purpose and relation to other functions).
* Consider [http://en.wikipedia.org/wiki/CamelCase headlessCamelCase] for the function name.
* Try to keep functions focused, that is, small, doing just one thing but doing it very well.
* When adding a new function, add unit test(s) for it as well.

==== put <tt>$self = __FUNCTION__;</tt> at the beginning of a recursive function ====
'''Why:''' to make it easier to see a recursive function. Such a function should call itself as <tt>$self(...)</tt> so that if the function is renamed later its code requires no changes to work.
<pre>
# Return a list consisting of tag ID of the given tree node and IDs of all
# nodes it contains.
function getTagIDListForNode ($treenode)
{
$self = __FUNCTION__;
$ret = array ($treenode['id']);
foreach ($treenode['kids'] as $item)
$ret = array_merge ($ret, $self ($item));
return $ret;
}
</pre>

==== prefer <tt>//</tt> over <tt>#</tt> for single-line comments ====
'''Why:''' it saves keystokes (double-press one key versus pressing two different keys simultaneously). However, when adding a comment to a code that already uses <tt>#</tt>, be consistent with what is already there.
Also, the code contains ~ 2000 of //-style lines versus ~450 of #-style.

==== don't use <tt>foreach()</tt> by reference ====
'''Why:''' this valid language construct has a side effect that complicates things. Consider the following code:
<pre>
$a = array (1 => 'a', 2 => 'b', 3 => 'c');
foreach ($a as &$tmp)
$tmp = $tmp . '_str';
</pre>
So far so good, but once you decide to reuse <tt>$tmp</tt> and assign a new value to it, you will [unexpectedly] modify the array (<tt>$tmp</tt> still holds the reference to the last element). [https://bugs.php.net/bug.php?id=37410 This thread] discusses the workings of this at length. The workaround would be to use <tt>unset ($tmp)</tt> after the foreach-by-reference, but the least-surprising solution is to iterate over array keys if you need to modify array elements and <tt>array_walk()</tt> is not sufficient:
<pre>
foreach (array_keys ($a) as $k)
$a[$k] = $a[$k] . '_str';
</pre>

==== use double-quotes for strings only when necessary ====
'''Why:''' it saves the time required to tell "just strings" from strings that embed expansions. Consider the following:
<pre>
$string1 = 'Single-quotes give a hint that this string is just a string.';
$string2 = "Double-quotes give a hint that this string not just _may_ contain " .
"expansions but it actually does: here are $var1 and ${var2}";
</pre>

==== use <tt>array_key_exists()</tt> instead of <tt>isset()</tt> to test a key in an array ====
'''Why:''' with <tt>isset()</tt> it is impossible to distinguish a missing element from a typo in the array name:
<pre>
$arr = array (1 => 'a', 2 => 'b');
if (array_key_exists (10, $arr)) # FALSE
echo 'OK';
if (array_key_exists (10, $ar)) # FALSE and a PHP warning (note the typo)
echo 'OK';
if (isset ($arr[10])) # FALSE
echo 'OK';
if (isset ($ar[10])) # FALSE and no warning
echo 'OK';
</pre>

==== keep the PHP code compatible with PHP 5.5 and 5.6 ====
'''Why:''' because some long-term supported distributions still support these versions, and that's what the users still use in production.

==== keep the PHP code compatible with PHP versions 7.x ====
'''Why:''' because newer PHP versions tend to deprecate functions and extensions, so you have to account for that.

==== use "&&" and "||", not "and" and "or" ====
'''Why:''' because (unlike, for instance, C++) those are not just alternative notations but quite different operators. From the [http://php.net/manual/en/language.operators.precedence.php PHP operator precedence table] it is possible to see that, for example, the following two lines of code work in a very different way:
<pre>
$c = $a or $b; // Evaluate $a and assign the value to $c. If $c was set to false, evaluate $b and discard the value.
$c = $a || $b; // Evaluate $a. If the value is true, set $c to true. Otherwise evaluate $b and assign the value to $c.
</pre>
Not everybody remembers about this difference and eventually interprets the code not as PHP actually executes it. As the gain of "and" and "or" in RackTables is negligible, the simplest solution is not to use them at all.

==== test for an empty string in the simplest way possible ====
Just compare with an empty string. Only use <tt>strlen()</tt> and <tt>mb_strlen()</tt> when those are really required, i.e. when it is necessary to know the exact length of a string or a multibyte string.
<pre>
if ($s == '') // OK
...
if ($s != '') // OK
...
if (strlen ($s)) // overkill
...
if (! strlen ($s)) // overkill
...
if (mb_strlen ($s)) // overkill
...
if (! mb_strlen ($s)) // overkill
...
</pre>

==== use uppercase for NULL, TRUE and FALSE ====
'''Why:''' because PHP documentation always spells it this way, so let's keep it readbale (PHP interpreter itself is case-insensitive in this regard).

== SQL code style guide ==
==== use uppercase for SQL keywords and wrap long lines ====
'''Why:''' readability
<pre>
$result = usePreparedSelectBlade
(
'SELECT FileLink.file_id, FileLink.id AS link_id, name, type, size, ctime, mtime, atime, comment ' .
'FROM FileLink LEFT JOIN File ON FileLink.file_id = File.id ' .
'WHERE FileLink.entity_type = ? AND FileLink.entity_id = ? ORDER BY name',
array ($entity_type, $entity_id)
);
</pre>

==== use SELECT with an explicit list of columns, don't use <tt>SELECT *</tt> ====
'''Why:''' this is very well explained in many sources, for instance, [http://stackoverflow.com/questions/3639861/why-is-select-considered-harmful here] and [http://use-the-index-luke.com/blog/2013-08/its-not-about-the-star-stupid here].

Main Page

2019-12-07T20:45:47Z

Infrastation: update a reference to point to maintenance-0.21.x

[[File:RackTables-development-roadmap-2019Q4.png|311px|thumb|right]]
* for RackTables users
** The [https://github.com/RackTables/racktables/blob/maintenance-0.21.x/README.md README file] now replaces the old Installation HOWTO.
** [[RackTablesAdminGuide | Administrator's guide]]
** [[RackTablesUserGuide | User's guide]]
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)
** [[FAQ]]
** [[LDAP | LDAP authentication]]
** [[SAML | SAML authentication]]
* for RackTables hackers
** [[SourceCode | Working with RackTables source code]]
** [[RackTablesDevelGuide | Developer's guide]]
** [[FeatureWishlist | Feature wishlist]]
** [[Gateways | Extending RackTables with gateways]]
** [[Plugins | Extending RackTables with plugins]]
* for development team
** [[NewRelease | Checklist and procedures to make a new release]]
** [[ProjectInfrastructure | Project infrastructure]]
** [[Roadmap]]

Main Page

2019-11-24T15:52:38Z

Infrastation: use the new roadmap

[[File:RackTables-development-roadmap-2019Q4.png|311px|thumb|right]]
* for RackTables users
** The [https://github.com/RackTables/racktables/blob/maintenance-0.20.x/README.md README file] now replaces the old Installation HOWTO.
** [[RackTablesAdminGuide | Administrator's guide]]
** [[RackTablesUserGuide | User's guide]]
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)
** [[FAQ]]
** [[LDAP | LDAP authentication]]
** [[SAML | SAML authentication]]
* for RackTables hackers
** [[SourceCode | Working with RackTables source code]]
** [[RackTablesDevelGuide | Developer's guide]]
** [[FeatureWishlist | Feature wishlist]]
** [[Gateways | Extending RackTables with gateways]]
** [[Plugins | Extending RackTables with plugins]]
* for development team
** [[NewRelease | Checklist and procedures to make a new release]]
** [[ProjectInfrastructure | Project infrastructure]]
** [[Roadmap]]

File:RackTables-development-roadmap-2019Q4.png

2019-11-24T15:50:38Z

Infrastation:

NewRelease

2019-11-17T20:56:30Z

Infrastation: /* updating demo */ add a missing parameter

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git add ChangeLog wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo yes
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

NewRelease

2019-11-17T20:52:06Z

Infrastation: /* producing and publishing deliverables */ SF downloads no longer have buttons

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git add ChangeLog wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

NewRelease

2019-11-17T20:28:22Z

Infrastation: /* producing and publishing deliverables */ remove unnecessary export

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git add ChangeLog wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

NewRelease

2019-06-12T14:12:09Z

Infrastation: /* part 1 */ simplify the git command

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git add ChangeLog wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

NewRelease

2019-06-12T13:51:32Z

Infrastation: /* part 1 */ fixup some language

== pre-release checklist ==
=== part 1 ===
Make sure all necessary changes have been committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git status
git add ChangeLog
[...]
git add wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

Main Page

2019-06-12T12:25:49Z

Infrastation: use the new roadmap

[[File:RackTables-development-roadmap-2019Q2.png|409px|thumb|right]]
* for RackTables users
** The [https://github.com/RackTables/racktables/blob/maintenance-0.20.x/README.md README file] now replaces the old Installation HOWTO.
** [[RackTablesAdminGuide | Administrator's guide]]
** [[RackTablesUserGuide | User's guide]]
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)
** [[FAQ]]
** [[LDAP | LDAP authentication]]
** [[SAML | SAML authentication]]
* for RackTables hackers
** [[SourceCode | Working with RackTables source code]]
** [[RackTablesDevelGuide | Developer's guide]]
** [[FeatureWishlist | Feature wishlist]]
** [[Gateways | Extending RackTables with gateways]]
** [[Plugins | Extending RackTables with plugins]]
* for development team
** [[NewRelease | Checklist and procedures to make a new release]]
** [[ProjectInfrastructure | Project infrastructure]]
** [[Roadmap]]

File:RackTables-development-roadmap-2019Q2.png

2019-06-12T12:24:28Z

Infrastation:

Gateways

2019-03-31T23:54:36Z

Infrastation: /* List of device commands */ describe getmaclist and getportmaclist

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table (for all ports) as an array.
|-
| <tt>getportmaclist</tt>
| Returns the MAC address table (for a specific port only) as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}

==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>hpprocurveN1178</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios15</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp85</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:51:37Z

Infrastation: /* Implementation matrix */ add hpprocurveN1178

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>hpprocurveN1178</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios15</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp85</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:48:38Z

Infrastation: /* Implementation matrix */ add ios15

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios15</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp85</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:47:05Z

Infrastation: /* Implementation matrix */ add vrp85

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp85</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:39:22Z

Infrastation: /* Implementation matrix */ update xos12

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:38:04Z

Infrastation: /* Implementation matrix */ update fdry5

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
|
| bgcolor=green |
|
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:35:37Z

Infrastation: /* Implementation matrix */ add getportmaclist

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
|
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
|
| bgcolor=green |
|
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:09:17Z

Infrastation: /* List of device breeds */ add vrp85

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>vrp85</tt>
| Huawei VRP release 8.5
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-31T23:06:45Z

Infrastation: /* List of device breeds */ fixup the order of entries

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

Gateways

2019-03-29T10:09:45Z

Infrastation: /* List of device breeds */ list the breeds added in 0.21.2

==What are RackTables gateways==
RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: '''netcat''', '''telnet''' and '''ssh'''. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.

==List of device breeds==
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
| <tt>air12</tt>
| Cisco Aironet IOS release 12.x
|-
| <tt>dlink</tt>
| D-Link, unknown release
|-
| <tt>eos4</tt>
| Arista EOS release 4.x
|-
| <tt>fdry5</tt>
| Foundry Networks IronWare release 5.x
|-
| <tt>ftos8</tt>
| Force10 FTOS release 8.x
|-
| <tt>ios12</tt>
| Cisco Catalyst IOS release 12.x
|-
| <tt>ios15</tt>
| Cisco IOS release 15.x
|-
| <tt>iosxr4</tt>
| Cisco XR IOS release 4.2
|-
| <tt>jun10</tt>
| Juniper JunOS releases 10, 11 and 12
|-
| <tt>linux</tt>
| generic Linux
|-
| <tt>nxos4</tt>
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
|-
| <tt>ros11</tt>
| Marvell ROS release 1.1
|-
| <tt>ucs</tt>
| Cisco UCS
|-
| <tt>vrp53</tt>
| Huawei VRP release 5.3
|-
| <tt>vrp55</tt>
| Huawei VRP releases 5.5 and 5.7
|-
| <tt>xos12</tt>
| Extreme Networks XOS release 12
|-
| <tt>hpprocurveN1178</tt>
| HP N.11.78
|}

==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
| <tt>xlatepushq</tt>
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
|-
| <tt>get8021q</tt>
| Returns the 802.1Q configuration of the device as a list of arrays.
|-
| <tt>getallconf</tt>
| Returns the device's current configuration as a string in native plain-text format (multiline).
|-
| <tt>getcdpstatus</tt>
| Returns the list of CDP neighbors as an array.
|-
| <tt>getlldpstatus</tt>
| Returns the list of LLDP neighbors as an array.
|-
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
|-
| <tt>getportstatus</tt>
| Returns the full list of network interfaces as an array.
|-
| <tt>getinventory</tt>
| Returns a list of hardware components as an array.
|}
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
|
| <tt>xlatepushq</tt>
| <tt>get8021q</tt>
| <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
| <tt>getportstatus</tt>
| <tt>getinventory</tt>
|-
| <tt>air12</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|-
| <tt>dlink</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>eos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>fdry5</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|-
| <tt>ftos8</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ios12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>iosxr4</tt>
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|
|
|-
| <tt>jun10</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|
|
|
|
|-
| <tt>linux</tt>
| bgcolor=green |
| bgcolor=green |
|
|
|
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>nxos4</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ros11</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>ucs</tt>
| bgcolor=green |
|
|
|
|
|
|
| bgcolor=green |
|-
| <tt>vrp53</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>vrp55</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
|-
| <tt>xos12</tt>
| bgcolor=green |
| bgcolor=green |
| bgcolor=green |
|
| bgcolor=green |
|
|
|
|}

==File layout==
The gateways part consist of two file sets:
* PHP files stored in wwwroot/inc/ dir:
*; <tt>deviceconfig.php</tt>
*: Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
*; <tt>remote.php</tt>
*: The current 0.20.x gateways API. This file normally requires no changes.
*; <tt style="text-decoration: line-through">gateways.php</tt>
*: Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2

* CLI tools stored in gateways/ dir:
*; <tt>netcat ssh sshnokey telnet ucssdk</tt>
*: CLI-mode clients providing a particular communication protocol.
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt>
*: Old-style CLI tools. Removed in 0.20.2.
;

==Key API functions==
There are two core functions:
<pre>
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)
</pre>

== Setting up queryTerminal function ==
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to
collect the parameters. This function is responsible for overriding of connection properties based on
local policy. Most of the re-definable parameters have reasonable default values, but username and
password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':
<pre>
$params = array (array
(
'hostname' => $endpoints[0], // either hostname or IP
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
'username' => NULL,
'password' => NULL,
'timeout' => 15,
'connect_timeout' => 2,
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
));
</pre>

Typical implementation of this user-defined callback looks like this:

<pre>
function terminal_settings ($cell, $params)
{
// servers and Juniper routers use ssh, other - telnet
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 5;
}
else
{
$params[0]['protocol'] = 'telnet';
$params[0]['username'] = 'username';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 30;
}
}
</pre>

You can put your definition of terminal_settings function into your secret.php file.

SourceCode

2019-01-22T21:05:40Z

Infrastation: /* the source code repository */ reword and reference the git mirror

== the source code repository==
RackTables project uses git as version control system for the source code ([https://github.com/RackTables/racktables GitHub], [http://code.racktables.org/ read-only mirror]). The repository includes the following notable branches:
;master
:The main development branch, that is, the default branch for all new changes.
;maintenance-0.16.x
;maintenance-0.17.x
;maintenance-0.18.x
;maintenance-0.19.x
;maintenance-0.20.x
:Archived maintenance branches, which do not accept any new changes.

Use the following commands to get a working copy of the repository:
<pre>
# from the RackTables project repository
git clone git://github.com/RackTables/racktables.git
# or
git clone https://github.com/RackTables/racktables.git
# or
git clone ssh://git@github.com:RackTables/racktables.git

# from a GitHub fork (of your own or not)
git clone git://github.com/username/racktables.git
# or
git clone https://github.com/username/racktables.git
# or
git clone ssh://git@github.com:username/racktables.git
</pre>
Note that the first two schemas (<tt>git://</tt> and <tt>https://</tt>) are always '''read-only''' and the third (<tt>ssh://</tt>) may be '''read-only or read-write'''.

Use the following commands to examine local unsaved changes:
<pre>
git status
git diff
</pre>

The recommended way of contributing the work is to:
# fork RackTables on GitHub,
# push finished commits to the fork, and
# create a pull request.

In the case of a private repository use a [http://git-scm.com/docs/git-format-patch git format-patch] command to produce a patch and send it to the developers. When sending a patch, please make sure your branch is [http://git-scm.com/book/en/Git-Branching-Rebasing rebased] onto the latest respective (master or maintenance) branch.

== PHP code style guide ==
Almost all PHP source code in RackTables is original and the following style guide applies:
==== use [http://en.wikipedia.org/wiki/Indent_style#Allman_style Allman] indent style. ====
'''Why:''' Allman style is very diff-friendly when it comes to control structures. In Allman style expansion of a single inner operator into a larger code block (and vice versa) leaves both the inner (controlled) and the outer (controlling) operator intact:
<pre>
for ($i = 0; $i < 10; $i++)
+{
doSomething ($i);
+ doSomethingElse();
+}
</pre>
This works seamlessly at any indentation level and for all control structures (<tt>if/for/foreach/while</tt>), however deeply nested in each other. With careful indentation of <tt>case</tt> within <tt>switch</tt> it will work same well:
<pre>
switch ($var)
{
case 1:
doSomething();
break;
case 2:
- {
- doSomethingElse();
return 3;
- }
case 3:
+ {
+ doSomethingCompletelyDifferent();
return 4;
+ }
}
</pre>
Being diff-friendly means being friendly to a version control system (Subversion in the past, git at present). Neither the VCS nor the Allman style alone guarantee one's commits to be focused and clean. However, Allman style encourages commits that change only the lines that really need to be changed.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

==== use exactly one tab per indentation level ====
'''Why:''' different people prefer different (2, 4, 8...) amount of "spaces" per indentation level. Some projects use space indentation and force everyone to hit Space (Backspace) N times each time the developer needs to indent (unindent), regardless of their own preferred value of N. RackTables makes use of Tab and enables every developer to configure their editor for their preferred "tab width" (the screenshot below stands for tab width 2). Note that the tab width must stand for the amount of spaces the editor ''displays'', but not ''generates instead of'', that is, in the source file '''tabs must remain tabs'''.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

[[File:interface_tab2.png]]

==== wrap lines longer than 100-120 characters ====
'''Why:''' readability. Prior experience tells that old-school 80-columns margin just doesn't work with descriptive naming of variables and functions (i.e. descriptive == heavily wrapped). On the other hand, avoid making a readable, 200-characters long line even if it fits your monitor. Use good judgement.

==== consider using indentation/alignment for function arguments ====
'''Why:''' the purpose is twofold. On one hand it allows to pack a lot of arguments and expressions into a single function call without losing track of what is being done and no temporary variables:
<pre>
usePreparedUpdateBlade
(
'Port',
array
(
'name' => $port_name,
'type' => $port_type_id,
'label' => $port_label,
'reservation_comment' => $reservation_comment,
'l2address' => nullEmptyStr ($db_l2address),
),
array
(
'id' => $port_id,
'object_id' => $object_id
)
);
</pre>
On the other hand, it allows to group function arguments add/or add comments to them:
<pre>
function get8021QSyncOptions
(
$vswitch,
$D, // desired config
$C, // cached config
$R // running-config
)
{
$default_port = array
(
'mode' => 'access',
'allowed' => array (VLAN_DFL_ID),
'native' => VLAN_DFL_ID,
);
$ret = array();
</pre>
Use good judgement.

==== consider using indentation/alignment for arrays ====
'''Why:''' due to a few reasons. First, multiline array assignment/initialization can accommodate a notable amount of supplementary expressions:
<pre>
$ret[$pn] = array
(
'status' => 'martian_conflict',
'left' => array_key_exists ($pn, $C) ? $C[$pn] : array ('mode' => 'none'),
'right' => array_key_exists ($pn, $R) ? $R[$pn] : array ('mode' => 'none'),
);
</pre>
Second, updates to arrays that serve as lists produce cleaner diffs, for example:
<pre>
--- a/wwwroot/inc/remote.php
+++ b/wwwroot/inc/remote.php
@@ -64,6 +64,7 @@ $breedfunc = array
'jun10-get8021q-main' => 'jun10Read8021QConfig',
'jun10-xlatepushq-main' => 'jun10TranslatePushQueue',
'jun10-getallconf-main' => 'jun10SpotConfigText',
+ 'jun10-getlldpstatus-main' => 'jun10ReadLLDPStatus',
'ftos8-xlatepushq-main' => 'ftos8TranslatePushQueue',
'ftos8-getlldpstatus-main' => 'ftos8ReadLLDPStatus',
'ftos8-getmaclist-main' => 'ftos8ReadMacList',
</pre>
Finally, it makes tree-like array initialization more transparent:
<pre>
$SQLSchema = array
(
'object' => array
(
'table' => 'RackObject',
'columns' => array
(
'id' => 'id',
'name' => 'name',
'label' => 'label',
'asset_no' => 'asset_no',
'objtype_id' => 'objtype_id',
'rack_id' => '(SELECT MIN(rack_id) FROM RackSpace WHERE object_id = RackObject.id)',
'rack_id_2' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'rack')",
'container_id' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'object')",
'container_name' => '(SELECT name FROM RackObject WHERE id = container_id)',
'container_objtype_id' => '(SELECT objtype_id FROM RackObject WHERE id = container_id)',
'has_problems' => 'has_problems',
'comment' => 'comment',
'nports' => '(SELECT COUNT(*) FROM Port WHERE object_id = RackObject.id)',
'8021q_domain_id' => '(SELECT domain_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
'8021q_template_id' => '(SELECT template_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
),
'keycolumn' => 'id',
'ordcolumns' => array ('RackObject.name'),
),
</pre>

==== put <tt>else</tt> near its <tt>if</tt> ====
When an <tt>if</tt> operator includes the <tt>else</tt> part, consider arranging the branches so that the short branch belongs to the <tt>if</tt> and the long branch belongs to the <tt>else</tt>. '''Why:''' it helps following the code.

Holub, Allen (1995). Enough Rope to Shoot Yourself in the Foot. McGraw-Hill. ISBN 978-0-07-029689-3
"Section 57: Put the shortest clause of an <tt>if/else</tt> on top."

==== make conscise use of the [http://en.wikipedia.org/wiki/%3F: conditional ternary operator] ====
'''Why:''' to use the language element in making the code look closer to what the code is intended to do. First, don't reinvent the conditional ternary operator with <tt>if</tt> like this:
<pre>
if ($row !== FALSE)
return $row[0];
else
return NULL;
</pre>
That block of code returns a value in either case, exactly one <tt>return</tt> would do the job:
<pre>
return $row === FALSE ? NULL : $row[0];
</pre>

Second, don't nest ternary conditionals, it is hard to read:
<pre>
$ret = ($ret > 0 ? 1 : ($ret < 0 ? -1 : 0));
</pre>
For that specific case use <tt>numSign()</tt>.

Finally, when a standalone ternary conditional isn't sufficient or is long/difficult to read, use temporary variables or necessary amount of <tt>if</tt>'s.

==== things to consider when adding a new function ====
* First, is it possible to use one of the existing functions or a combination of these?
* Carefully decide which file the function should be in (depends on its purpose and relation to other functions).
* Consider [http://en.wikipedia.org/wiki/CamelCase headlessCamelCase] for the function name.
* Try to keep functions focused, that is, small, doing just one thing but doing it very well.
* When adding a new function, add unit test(s) for it as well.

==== put <tt>$self = __FUNCTION__;</tt> at the beginning of a recursive function ====
'''Why:''' to make it easier to see a recursive function. Such a function should call itself as <tt>$self(...)</tt> so that if the function is renamed later its code requires no changes to work.
<pre>
# Return a list consisting of tag ID of the given tree node and IDs of all
# nodes it contains.
function getTagIDListForNode ($treenode)
{
$self = __FUNCTION__;
$ret = array ($treenode['id']);
foreach ($treenode['kids'] as $item)
$ret = array_merge ($ret, $self ($item));
return $ret;
}
</pre>

==== prefer <tt>//</tt> over <tt>#</tt> for single-line comments ====
'''Why:''' it saves keystokes (double-press one key versus pressing two different keys simultaneously). However, when adding a comment to a code that already uses <tt>#</tt>, be consistent with what is already there.
Also, the code contains ~ 2000 of //-style lines versus ~450 of #-style.

==== don't use <tt>foreach()</tt> by reference ====
'''Why:''' this valid language construct has a side effect that complicates things. Consider the following code:
<pre>
$a = array (1 => 'a', 2 => 'b', 3 => 'c');
foreach ($a as &$tmp)
$tmp = $tmp . '_str';
</pre>
So far so good, but once you decide to reuse <tt>$tmp</tt> and assign a new value to it, you will [unexpectedly] modify the array (<tt>$tmp</tt> still holds the reference to the last element). [https://bugs.php.net/bug.php?id=37410 This thread] discusses the workings of this at length. The workaround would be to use <tt>unset ($tmp)</tt> after the foreach-by-reference, but the least-surprising solution is to iterate over array keys if you need to modify array elements and <tt>array_walk()</tt> is not sufficient:
<pre>
foreach (array_keys ($a) as $k)
$a[$k] = $a[$k] . '_str';
</pre>

==== use double-quotes for strings only when necessary ====
'''Why:''' it saves the time required to tell "just strings" from strings that embed expansions. Consider the following:
<pre>
$string1 = 'Single-quotes give a hint that this string is just a string.';
$string2 = "Double-quotes give a hint that this string not just _may_ contain " .
"expansions but it actually does: here are $var1 and ${var2}";
</pre>

==== use <tt>array_key_exists()</tt> instead of <tt>isset()</tt> to test a key in an array ====
'''Why:''' with <tt>isset()</tt> it is impossible to distinguish a missing element from a typo in the array name:
<pre>
$arr = array (1 => 'a', 2 => 'b');
if (array_key_exists (10, $arr)) # FALSE
echo 'OK';
if (array_key_exists (10, $ar)) # FALSE and a PHP warning (note the typo)
echo 'OK';
if (isset ($arr[10])) # FALSE
echo 'OK';
if (isset ($ar[10])) # FALSE and no warning
echo 'OK';
</pre>

==== keep the PHP code compatible with PHP 5.5 and 5.6 ====
'''Why:''' because some long-term supported distributions still support these versions, and that's what the users still use in production.

==== keep the PHP code compatible with PHP versions 7.x ====
'''Why:''' because newer PHP versions tend to deprecate functions and extensions, so you have to account for that.

==== use "&&" and "||", not "and" and "or" ====
'''Why:''' because (unlike, for instance, C++) those are not just alternative notations but quite different operators. From the [http://php.net/manual/en/language.operators.precedence.php PHP operator precedence table] it is possible to see that, for example, the following two lines of code work in a very different way:
<pre>
$c = $a or $b; // Evaluate $a and assign the value to $c. If $c was set to false, evaluate $b and discard the value.
$c = $a || $b; // Evaluate $a. If the value is true, set $c to true. Otherwise evaluate $b and assign the value to $c.
</pre>
Not everybody remembers about this difference and eventually interprets the code not as PHP actually executes it. As the gain of "and" and "or" in RackTables is negligible, the simplest solution is not to use them at all.

==== test for an empty string in the simplest way possible ====
Just compare with an empty string. Only use <tt>strlen()</tt> and <tt>mb_strlen()</tt> when those are really required, i.e. when it is necessary to know the exact length of a string or a multibyte string.
<pre>
if ($s == '') // OK
...
if ($s != '') // OK
...
if (strlen ($s)) // overkill
...
if (! strlen ($s)) // overkill
...
if (mb_strlen ($s)) // overkill
...
if (! mb_strlen ($s)) // overkill
...
</pre>

==== use uppercase for NULL, TRUE and FALSE ====
'''Why:''' because PHP documentation always spells it this way, so let's keep it readbale (PHP interpreter itself is case-insensitive in this regard).

== SQL code style guide ==
==== use uppercase for SQL keywords and wrap long lines ====
'''Why:''' readability
<pre>
$result = usePreparedSelectBlade
(
'SELECT FileLink.file_id, FileLink.id AS link_id, name, type, size, ctime, mtime, atime, comment ' .
'FROM FileLink LEFT JOIN File ON FileLink.file_id = File.id ' .
'WHERE FileLink.entity_type = ? AND FileLink.entity_id = ? ORDER BY name',
array ($entity_type, $entity_id)
);
</pre>

==== use SELECT with an explicit list of columns, don't use <tt>SELECT *</tt> ====
'''Why:''' this is very well explained in many sources, for instance, [http://stackoverflow.com/questions/3639861/why-is-select-considered-harmful here] and [http://use-the-index-luke.com/blog/2013-08/its-not-about-the-star-stupid here].

Main Page

2018-12-18T22:15:53Z

Infrastation: HTTPS is forced now

[[File:RackTables-development-roadmap-2017Q2.png|535px|thumb|right]]
* for RackTables users
** The [https://github.com/RackTables/racktables/blob/maintenance-0.20.x/README.md README file] now replaces the old Installation HOWTO.
** [[RackTablesAdminGuide | Administrator's guide]]
** [[RackTablesUserGuide | User's guide]]
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)
** [[FAQ]]
** [[LDAP | LDAP authentication]]
** [[SAML | SAML authentication]]
* for RackTables hackers
** [[SourceCode | Working with RackTables source code]]
** [[RackTablesDevelGuide | Developer's guide]]
** [[FeatureWishlist | Feature wishlist]]
** [[Gateways | Extending RackTables with gateways]]
** [[Plugins | Extending RackTables with plugins]]
* for development team
** [[NewRelease | Checklist and procedures to make a new release]]
** [[ProjectInfrastructure | Project infrastructure]]
** [[Roadmap]]

SourceCode

2018-11-13T10:34:50Z

Infrastation: /* don't use language features of PHP 5.3+ */ update and expand the comment about PHP versions

== the source code repository==
RackTables project uses git as version control system for the source code. The git repository that is used to make "tar.gz" releases is currently hosted on [https://github.com/RackTables/racktables GitHub]. It includes the following notable branches:
;master
:The main development branch, that is, the default branch for all new changes.
;maintenance-0.16.x
;maintenance-0.17.x
;maintenance-0.18.x
;maintenance-0.19.x
:Archived maintenance branches, which don't accept any new changes.
;maintenance-0.20.x
:Current maintenance branche, that is, the stable branch that serves as the base for normal RackTables releases.

Use the following commands to get a working copy of the repository:
<pre>
# from the RackTables project repository
git clone git://github.com/RackTables/racktables.git
# or
git clone https://github.com/RackTables/racktables.git
# or
git clone ssh://git@github.com:RackTables/racktables.git

# from a GitHub fork (of your own or not)
git clone git://github.com/username/racktables.git
# or
git clone https://github.com/username/racktables.git
# or
git clone ssh://git@github.com:username/racktables.git
</pre>
Note that the first two schemas (<tt>git://</tt> and <tt>https://</tt>) are always '''read-only''' and the third (<tt>ssh://</tt>) may be '''read-only or read-write'''.

Use the following commands to examine local unsaved changes:
<pre>
git status
git diff
</pre>

The recommended way of contributing the work is to:
# fork RackTables on GitHub,
# push finished commits to the fork, and
# create a pull request.

In the case of a private repository use a [http://git-scm.com/docs/git-format-patch git format-patch] command to produce a patch and send it to the developers. When sending a patch, please make sure your branch is [http://git-scm.com/book/en/Git-Branching-Rebasing rebased] onto the latest respective (master or maintenance) branch.

== PHP code style guide ==
Almost all PHP source code in RackTables is original and the following style guide applies:
==== use [http://en.wikipedia.org/wiki/Indent_style#Allman_style Allman] indent style. ====
'''Why:''' Allman style is very diff-friendly when it comes to control structures. In Allman style expansion of a single inner operator into a larger code block (and vice versa) leaves both the inner (controlled) and the outer (controlling) operator intact:
<pre>
for ($i = 0; $i < 10; $i++)
+{
doSomething ($i);
+ doSomethingElse();
+}
</pre>
This works seamlessly at any indentation level and for all control structures (<tt>if/for/foreach/while</tt>), however deeply nested in each other. With careful indentation of <tt>case</tt> within <tt>switch</tt> it will work same well:
<pre>
switch ($var)
{
case 1:
doSomething();
break;
case 2:
- {
- doSomethingElse();
return 3;
- }
case 3:
+ {
+ doSomethingCompletelyDifferent();
return 4;
+ }
}
</pre>
Being diff-friendly means being friendly to a version control system (Subversion in the past, git at present). Neither the VCS nor the Allman style alone guarantee one's commits to be focused and clean. However, Allman style encourages commits that change only the lines that really need to be changed.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

==== use exactly one tab per indentation level ====
'''Why:''' different people prefer different (2, 4, 8...) amount of "spaces" per indentation level. Some projects use space indentation and force everyone to hit Space (Backspace) N times each time the developer needs to indent (unindent), regardless of their own preferred value of N. RackTables makes use of Tab and enables every developer to configure their editor for their preferred "tab width" (the screenshot below stands for tab width 2). Note that the tab width must stand for the amount of spaces the editor ''displays'', but not ''generates instead of'', that is, in the source file '''tabs must remain tabs'''.

'''Exception:''' inline (PHP heredoc) HTML, SQL and JS code.

[[File:interface_tab2.png]]

==== wrap lines longer than 100-120 characters ====
'''Why:''' readability. Prior experience tells that old-school 80-columns margin just doesn't work with descriptive naming of variables and functions (i.e. descriptive == heavily wrapped). On the other hand, avoid making a readable, 200-characters long line even if it fits your monitor. Use good judgement.

==== consider using indentation/alignment for function arguments ====
'''Why:''' the purpose is twofold. On one hand it allows to pack a lot of arguments and expressions into a single function call without losing track of what is being done and no temporary variables:
<pre>
usePreparedUpdateBlade
(
'Port',
array
(
'name' => $port_name,
'type' => $port_type_id,
'label' => $port_label,
'reservation_comment' => $reservation_comment,
'l2address' => nullEmptyStr ($db_l2address),
),
array
(
'id' => $port_id,
'object_id' => $object_id
)
);
</pre>
On the other hand, it allows to group function arguments add/or add comments to them:
<pre>
function get8021QSyncOptions
(
$vswitch,
$D, // desired config
$C, // cached config
$R // running-config
)
{
$default_port = array
(
'mode' => 'access',
'allowed' => array (VLAN_DFL_ID),
'native' => VLAN_DFL_ID,
);
$ret = array();
</pre>
Use good judgement.

==== consider using indentation/alignment for arrays ====
'''Why:''' due to a few reasons. First, multiline array assignment/initialization can accommodate a notable amount of supplementary expressions:
<pre>
$ret[$pn] = array
(
'status' => 'martian_conflict',
'left' => array_key_exists ($pn, $C) ? $C[$pn] : array ('mode' => 'none'),
'right' => array_key_exists ($pn, $R) ? $R[$pn] : array ('mode' => 'none'),
);
</pre>
Second, updates to arrays that serve as lists produce cleaner diffs, for example:
<pre>
--- a/wwwroot/inc/remote.php
+++ b/wwwroot/inc/remote.php
@@ -64,6 +64,7 @@ $breedfunc = array
'jun10-get8021q-main' => 'jun10Read8021QConfig',
'jun10-xlatepushq-main' => 'jun10TranslatePushQueue',
'jun10-getallconf-main' => 'jun10SpotConfigText',
+ 'jun10-getlldpstatus-main' => 'jun10ReadLLDPStatus',
'ftos8-xlatepushq-main' => 'ftos8TranslatePushQueue',
'ftos8-getlldpstatus-main' => 'ftos8ReadLLDPStatus',
'ftos8-getmaclist-main' => 'ftos8ReadMacList',
</pre>
Finally, it makes tree-like array initialization more transparent:
<pre>
$SQLSchema = array
(
'object' => array
(
'table' => 'RackObject',
'columns' => array
(
'id' => 'id',
'name' => 'name',
'label' => 'label',
'asset_no' => 'asset_no',
'objtype_id' => 'objtype_id',
'rack_id' => '(SELECT MIN(rack_id) FROM RackSpace WHERE object_id = RackObject.id)',
'rack_id_2' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'rack')",
'container_id' => "(SELECT MIN(parent_entity_id) FROM EntityLink WHERE child_entity_type='object' AND child_entity_id = RackObject.id AND parent_entity_type = 'object')",
'container_name' => '(SELECT name FROM RackObject WHERE id = container_id)',
'container_objtype_id' => '(SELECT objtype_id FROM RackObject WHERE id = container_id)',
'has_problems' => 'has_problems',
'comment' => 'comment',
'nports' => '(SELECT COUNT(*) FROM Port WHERE object_id = RackObject.id)',
'8021q_domain_id' => '(SELECT domain_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
'8021q_template_id' => '(SELECT template_id FROM VLANSwitch WHERE object_id = id LIMIT 1)',
),
'keycolumn' => 'id',
'ordcolumns' => array ('RackObject.name'),
),
</pre>

==== put <tt>else</tt> near its <tt>if</tt> ====
When an <tt>if</tt> operator includes the <tt>else</tt> part, consider arranging the branches so that the short branch belongs to the <tt>if</tt> and the long branch belongs to the <tt>else</tt>. '''Why:''' it helps following the code.

Holub, Allen (1995). Enough Rope to Shoot Yourself in the Foot. McGraw-Hill. ISBN 978-0-07-029689-3
"Section 57: Put the shortest clause of an <tt>if/else</tt> on top."

==== make conscise use of the [http://en.wikipedia.org/wiki/%3F: conditional ternary operator] ====
'''Why:''' to use the language element in making the code look closer to what the code is intended to do. First, don't reinvent the conditional ternary operator with <tt>if</tt> like this:
<pre>
if ($row !== FALSE)
return $row[0];
else
return NULL;
</pre>
That block of code returns a value in either case, exactly one <tt>return</tt> would do the job:
<pre>
return $row === FALSE ? NULL : $row[0];
</pre>

Second, don't nest ternary conditionals, it is hard to read:
<pre>
$ret = ($ret > 0 ? 1 : ($ret < 0 ? -1 : 0));
</pre>
For that specific case use <tt>numSign()</tt>.

Finally, when a standalone ternary conditional isn't sufficient or is long/difficult to read, use temporary variables or necessary amount of <tt>if</tt>'s.

==== things to consider when adding a new function ====
* First, is it possible to use one of the existing functions or a combination of these?
* Carefully decide which file the function should be in (depends on its purpose and relation to other functions).
* Consider [http://en.wikipedia.org/wiki/CamelCase headlessCamelCase] for the function name.
* Try to keep functions focused, that is, small, doing just one thing but doing it very well.
* When adding a new function, add unit test(s) for it as well.

==== put <tt>$self = __FUNCTION__;</tt> at the beginning of a recursive function ====
'''Why:''' to make it easier to see a recursive function. Such a function should call itself as <tt>$self(...)</tt> so that if the function is renamed later its code requires no changes to work.
<pre>
# Return a list consisting of tag ID of the given tree node and IDs of all
# nodes it contains.
function getTagIDListForNode ($treenode)
{
$self = __FUNCTION__;
$ret = array ($treenode['id']);
foreach ($treenode['kids'] as $item)
$ret = array_merge ($ret, $self ($item));
return $ret;
}
</pre>

==== prefer <tt>//</tt> over <tt>#</tt> for single-line comments ====
'''Why:''' it saves keystokes (double-press one key versus pressing two different keys simultaneously). However, when adding a comment to a code that already uses <tt>#</tt>, be consistent with what is already there.
Also, the code contains ~ 2000 of //-style lines versus ~450 of #-style.

==== don't use <tt>foreach()</tt> by reference ====
'''Why:''' this valid language construct has a side effect that complicates things. Consider the following code:
<pre>
$a = array (1 => 'a', 2 => 'b', 3 => 'c');
foreach ($a as &$tmp)
$tmp = $tmp . '_str';
</pre>
So far so good, but once you decide to reuse <tt>$tmp</tt> and assign a new value to it, you will [unexpectedly] modify the array (<tt>$tmp</tt> still holds the reference to the last element). [https://bugs.php.net/bug.php?id=37410 This thread] discusses the workings of this at length. The workaround would be to use <tt>unset ($tmp)</tt> after the foreach-by-reference, but the least-surprising solution is to iterate over array keys if you need to modify array elements and <tt>array_walk()</tt> is not sufficient:
<pre>
foreach (array_keys ($a) as $k)
$a[$k] = $a[$k] . '_str';
</pre>

==== use double-quotes for strings only when necessary ====
'''Why:''' it saves the time required to tell "just strings" from strings that embed expansions. Consider the following:
<pre>
$string1 = 'Single-quotes give a hint that this string is just a string.';
$string2 = "Double-quotes give a hint that this string not just _may_ contain " .
"expansions but it actually does: here are $var1 and ${var2}";
</pre>

==== use <tt>array_key_exists()</tt> instead of <tt>isset()</tt> to test a key in an array ====
'''Why:''' with <tt>isset()</tt> it is impossible to distinguish a missing element from a typo in the array name:
<pre>
$arr = array (1 => 'a', 2 => 'b');
if (array_key_exists (10, $arr)) # FALSE
echo 'OK';
if (array_key_exists (10, $ar)) # FALSE and a PHP warning (note the typo)
echo 'OK';
if (isset ($arr[10])) # FALSE
echo 'OK';
if (isset ($ar[10])) # FALSE and no warning
echo 'OK';
</pre>

==== keep the PHP code compatible with PHP 5.5 and 5.6 ====
'''Why:''' because some long-term supported distributions still support these versions, and that's what the users still use in production.

==== keep the PHP code compatible with PHP versions 7.x ====
'''Why:''' because newer PHP versions tend to deprecate functions and extensions, so you have to account for that.

==== use "&&" and "||", not "and" and "or" ====
'''Why:''' because (unlike, for instance, C++) those are not just alternative notations but quite different operators. From the [http://php.net/manual/en/language.operators.precedence.php PHP operator precedence table] it is possible to see that, for example, the following two lines of code work in a very different way:
<pre>
$c = $a or $b; // Evaluate $a and assign the value to $c. If $c was set to false, evaluate $b and discard the value.
$c = $a || $b; // Evaluate $a. If the value is true, set $c to true. Otherwise evaluate $b and assign the value to $c.
</pre>
Not everybody remembers about this difference and eventually interprets the code not as PHP actually executes it. As the gain of "and" and "or" in RackTables is negligible, the simplest solution is not to use them at all.

==== test for an empty string in the simplest way possible ====
Just compare with an empty string. Only use <tt>strlen()</tt> and <tt>mb_strlen()</tt> when those are really required, i.e. when it is necessary to know the exact length of a string or a multibyte string.
<pre>
if ($s == '') // OK
...
if ($s != '') // OK
...
if (strlen ($s)) // overkill
...
if (! strlen ($s)) // overkill
...
if (mb_strlen ($s)) // overkill
...
if (! mb_strlen ($s)) // overkill
...
</pre>

==== use uppercase for NULL, TRUE and FALSE ====
'''Why:''' because PHP documentation always spells it this way, so let's keep it readbale (PHP interpreter itself is case-insensitive in this regard).

== SQL code style guide ==
==== use uppercase for SQL keywords and wrap long lines ====
'''Why:''' readability
<pre>
$result = usePreparedSelectBlade
(
'SELECT FileLink.file_id, FileLink.id AS link_id, name, type, size, ctime, mtime, atime, comment ' .
'FROM FileLink LEFT JOIN File ON FileLink.file_id = File.id ' .
'WHERE FileLink.entity_type = ? AND FileLink.entity_id = ? ORDER BY name',
array ($entity_type, $entity_id)
);
</pre>

==== use SELECT with an explicit list of columns, don't use <tt>SELECT *</tt> ====
'''Why:''' this is very well explained in many sources, for instance, [http://stackoverflow.com/questions/3639861/why-is-select-considered-harmful here] and [http://use-the-index-luke.com/blog/2013-08/its-not-about-the-star-stupid here].

NewRelease

2017-10-28T15:05:12Z

Infrastation: /* part 2 (unit testing) */ also run the large group of tests

== pre-release checklist ==
=== part 1 ===
First make sure that all necessary changes are already committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure that <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git status
git add ChangeLog
[...]
git add wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
./express.sh
phpunit --group large
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

FAQ

2017-10-27T13:09:54Z

Infrastation: /* Write a patch yourself. */ also mention GitHub PRs

= RackTables FAQ =

== How do I edit this wiki? ==
Send a message to devteam@racktables.org.

== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==
RackTables only supports some specific switch models, and yours is not one of them.

There are two ways to add support for new switch models. Both involve [http://bugs.racktables.org/bug_report_page.php filing a Mantis ticket].
=== Write a patch yourself. ===
# Review [[RackTablesDevelGuide#SNMP_sync|this text]] for background information.
# Add necessary changes to your copy of RackTables source code and test them.
# Propose the changes as a GitHub pull request or attach the patch to a new ticket in MantisBT.

=== Ask the developers to write a patch for you. ===
The following information is necessary.
* The exact model/part number of the device.
* For a device which features SFP (GBIC, X2 etc) pluggable ports, specify which of these pluggable ports are "combo" (IOW, alternate socket for a copper port under the same name) and which are standalone ports.
If possible, add the following information:
* Manufacturer's markup of device's ports (this can be "21, 22, 23, 24", "21X, 22X, 23X, 24X" or even "21, 22, 23C, 23F, 24C, 24F")
* Dump of SNMP info:
<pre>
snmpwalk -v 1 -c public switchname sysDescr.0
snmpwalk -On -v 1 -c public switchname sysObjectID.0
snmpwalk -v 1 -c public switchname ifTable
</pre>
If the device is modular or stackable, also walk ENTITY-MIB:
<pre>
snmpwalk -v 1 -c public switchname .1.3.6.1.2.1.47
</pre>
If the device is a Cisco stackable switch and its sysObjectID ends with .9.1.516, then enter the configuration command
<pre>
no snmp-server sysobjectid type stack-oid
</pre>
, reboot switch and re-collect the sysObjectID.0

Attach the information to the Mantis ticket. Do not post it inline, as it consumes too much screen real estate.

== Rack thumb images are broken ==
There are two common reasons for this:
# A mis-formatted local.php extension file. For images to work correctly, every PHP file of your RackTables, which begins with '''<?php''' tag, CAN NOT have a newline before the tag. Every PHP file of your RackTables, which ends with '''?>''' tag, CAN NOT have a newline after the tag.
# GD library is not working (although it probably was at the time of installation). This can be confirmed by means of phpinfo() and fixed with the help of package manager of your server and RackTables README file.

== How do I browse objects by object type? ==
On the "Objects" page under the "Tag filters" section there should be a text area where you can enter:
<pre>
{$typeid_XXX}
</pre>
Replace XXX with the Type ID of the type you are looking for. The easiest way to do that is to open object's page of an object that has the type you need and then to click the link next to the "Object type" header in the Summary block:<br>
[[File:Object_type.png]]

== How do I handle blade systems/modular switches? ==
You can have one object represent the chassis, and other objects represent the blades. See the documentation on [[RackTablesUserGuide#Containers|Containers]] for details.

== How do I re-order racks in a row? ==
In versions prior to 0.20, RackTables sorts in alphabetical order. A work-around is to prefix each rack's name with a number:
* "01 F14"
* "02 E14"
* "03 D14"
* "04 C14"
* "05 B14"
* "06 A14"

Starting with 0.20, you can manually sort racks. View the row, then click the "Manage racks" tab.

== How do I log out (and log in after that?) ==
To log out: Use the "Click here to logout" link. When presented with the username/password prompt, do not enter anything. Instead, press "Cancel".

To log in: Press your browser's "back" button to return to any of the normal pages (without "index.php?logout" in the URL) and enter your username/password.

== How do I enable IPv4 for object type X in versions before 0.20.6? ==
Answered by Ray Robertson:
<code>
Configuration --> User Interface --> Change

Edit the entry for 'List source: IPv4-enabled objects'

e.g.
List source: IPv4-enabled objects {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798}

To determine an object's typeid, hover your mouse pointer over the 'Object type' field when viewing the object. The typeid will be revealed in the URL.
</code>

'''Scenario:'''

At Company X you have a proprietary transceiver-type device that is network accessible & can be assigned an IP. You add a new RackObjectType called "Transceiver". To add the IPv4 tab to new "Transceiver" objects, do the following.

<code>
1. Navigate to Main > Configuration > Dictionary > RackObjectType.

2. Mouse-over the new RackObjectType you created, in this case "Transceiver". In this example, the Transceiver typeid is 50012.

3. Now navigate to Main > Configuration > User Interface > Change.

4. Scroll down to the item/entry "List source: IPv4-enabled objects".

5. Now go to the end of the line, and enter "or {$typeid_50012}".

6. Your new line looks like: {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798} or {$typeid_50012}

7. Save changes.

8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.
</code>

==How do I decode the IPv4 addresses stored in RackTables MySQL database?==
RackTables stores all IPv4 addresses in their natural representation (32-bit unsigned integers like 180879936). The most reliable way is to use RackTables PHP function spotEntity(), which will return a structure filled with assorted fields, including a dotted-quad representation of IP address. If for whatever reason you decide to fetch the data directly from MySQL database, the simplest way of converting the intergers to dotted-quad (10.200.2.64) form and back is to use MySQL's functions INET_NTOA() and INET_ATON() respectively:
<pre>
mysql> SELECT ip, INET_NTOA(ip), mask FROM IPv4Network;
+-----------+---------------+------+
| ip | INET_NTOA(ip) | mask |
+-----------+---------------+------+
| 180879360 | 10.200.0.0 | 31 |
| 180879362 | 10.200.0.2 | 31 |
| 180879364 | 10.200.0.4 | 31 |
| 180879366 | 10.200.0.6 | 31 |
| 180879616 | 10.200.1.0 | 26 |
| 180879680 | 10.200.1.64 | 26 |
| 180879872 | 10.200.2.0 | 26 |
| 180879936 | 10.200.2.64 | 26 |
| 180880192 | 10.200.3.64 | 26 |
| 180880384 | 10.200.4.0 | 26 |
| 180880448 | 10.200.4.64 | 26 |
+-----------+---------------+------+
11 rows in set (0.00 sec)
</pre>

==Is there a simpler way to export IP addresses?==
The method above has some disadvantages: IPv6 addresses are stored in different format, you aren't able to filter the objects to export using RackCode. In general, users should prefer to write PHP exporters rather than SQL ones. Here is an example of a simple exporter printing all IP allocaions for objects tagged by {debian wheezy}:

<pre>
<?php
$script_mode = TRUE;
require 'wwwroot/inc/init.php';
foreach (scanRealmByText ('object', '{debian wheezy}') as $object)
{
amplifyCell ($object);
foreach ($object['ipv4'] + $object['ipv6'] as $ip_bin => $alloc)
echo implode ("\t", [ $object['name'], $alloc['osif'], ip_format ($ip_bin) ]) . "\n";
}
</pre>

==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==
This is a known issue. The workaround is to upgrade from 0.17.x to 0.18.7, then to 0.19.x. Release 0.18.7 can be downloaded directly from the git repository: https://github.com/RackTables/racktables/zipball/RackTables-0.18.7

==How do I manage tags on a series of objects (networks etc) automaticaly?==
<pre>
<?php

$script_mode = TRUE;
include '/usr/local/racktables/wwwroot/inc/init.php';

# add tag "right" to each object tagged "left"
$added = getTagByName ('right');
foreach (scanRealmByText ('object', '{left}') as $object)
rebuildTagChainForEntity ('object', $object['id'], array ($added));

# remove tag "left" from each object tagged "right"
$removed = getTagByName ('left');
foreach (scanRealmByText ('object', '{left}') as $object)
deleteTagForEntity ('object', $object['id'], $removed['id']);

?>
</pre>

= RackTables contributions =
== How can I visualise network topology? ==
See [[Visualisation with GraphViz]] for ideas using GraphViz.

NewRelease

2017-10-05T16:46:03Z

Infrastation: /* updating the main web-site */ update the steps after the switch from SF

== pre-release checklist ==
=== part 1 ===
First make sure that all necessary changes are already committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure that <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git status
git add ChangeLog
[...]
git add wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
./tests/express.sh
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
* On the web-server run <tt>git pull</tt>.
* Open https://racktables.org and test the "download" link to work.

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

ProjectInfrastructure

2017-10-02T16:30:29Z

Infrastation: Update for the recent SF vhost cease.

==Mapping of assets==
=== DNS ===
racktables.org domain is currently registered through GoDaddy, which also provides 2 free nameservers. Aaron manages the domain.

=== racktables.org mail ===
racktables.org mail is handled by zohomail.com. Zoho Mail offers free service for up to three e-mail addresses. Two mailing lists exist, "devteam" and "info", which are setup to forward all messages to every development team member.

=== racktables-users mail ===
FreeLists is a great free service without accompanying advertisements. The only drawback about it is that it is non-profit and can go down some day, hence '''make sure the list of subscribers is present in a recent backup tarball'''.

To manage the mailing list, go to [http://www.freelists.org/login.html this page] and use the form to the left. Input your email subscribed to the list. If you don't remember your password, log in with an empty password, in this case the system will email you a one-time token to input on the next screen. Once logged in, you will see a very long SELECT with all lists of FreeLists. Click on the SELECT and press "r" to get to items starting with R. Select racktables-users and press "Select list" below. On the next screen press "Admin Menu". To manage individual subscribers, select one on the "Current List Users" SELECT and press "User Options". VACATION, MODPOST and NOPOST are the most frequently used flags, their meaning is explained inline.

Please think twice before changing any of the list-wide settings on the "Edit List Config" menu, these settings influence all subscribers of racktables-users.

=== All web-sites (demo, bugs, wiki, www) ===
Arnaud Launay is the server administrator. To get SSH access there, be a team member and find someone who already has access.

=== Statistics ===
SF download stats work for the downloads. Google analytics works for the content of racktables.org and demo.racktables.org (it does not currently display its admin interface in every browser).

=== downloads ===
SourceForge project FRS (File Release System, a CDN of sorts).
----

==Backup procedure==
===the backup directory===
mkdir RackTables-project-backup-`date +%Y%m%d`
cd RackTables-project-backup-`date +%Y%m%d`

===racktables-users mailing list===
Send an empty email with subject "who racktables-users" to ecartis@freelists.org and you will get a list of all subscribers. Save it to the backup directory as "racktables-users.txt".

===Git repositories===
git clone --mirror git://github.com/RackTables/racktables.git racktables.git
git clone --mirror git://github.com/RackTables/racktables-contribs.git racktables-contribs.git

===Bug tracker, wiki data, www===
SSH into the host and create a new backup directory.
mkdir ~/RackTables-apps-backup
cd ~/RackTables-apps-backup

Copy the applications into the backup directory on the server. This is important because they contain uploaded files and configuration settings.
tar czf bugs.tar.gz ~/www/bugs
tar czf wiki.tar.gz ~/www/wiki
tar czf www.tar.gz ~/www/www

Export the database for each application.
mysqldump -u <username> -p <dbname> > bugs.sql
mysqldump -u <username> -p <dbname> > wiki.sql

SCP the remote server directory to the local backup directory, then remove it from the server.

===Final check===
Now the backup directory must have these files/directories:
* racktables.git
* racktables-contribs.git
* racktables-users.txt
* RackTables-apps-backup
** wiki.tar.gz
** wiki.sql
** bugs.tar.gz
** bugs.sql
** www.tar.gz
'''SAVE THE BACKUP FOLDER TO A SAFE PLACE'''

Plugins

2017-10-02T16:25:21Z

Infrastation: Remove the warning.

== Overview ==
Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.

Note that this guide details features that may or may not be included in a future release.

=== States ===
A plugin may be in one of three states.
* Not installed - it exists in the plugins directory, but hasn't been installed yet
* Enabled - it has been installed and is active
* Disabled - it has been installed and was subsequently disabled

=== Administration ===
To install a plugin, first copy it to the "plugins" directory. Then visit the Configuration -> Plugins page and click the Edit tab. The new plugin should be listed with a state of "Not installed". Click the Install icon.

To upgrade a plugin, first backup the appropriate "plugins" sub-directory. To be safe, it's also a good idea to backup your entire database. Afterwards, copy over the new version into the "plugins" directory. When you visit the Edit tab of the Configuration -> Plugins page, you should see a variance in the Code Version and DB Version columns. Click the Upgrade icon.

== Writing a Plugin ==
The old procedure involves placing a PHP file in the "plugins" directory of your RackTables installation. That method has limited functionality and may be deprecated at a later date.

A new plugin architecture was introduced in version 0.21.0. It includes the ability to install, uninstall, enable and disable plugins from the web interface. It is assumed that each plugin resides in its own directory within the main "plugins" directory, and that each plugin contains a "plugin.php" file which includes certain functions. The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.

=== Files ===
Each plugin is expected to contain certain files. While the only required file is "plugin.php", it is recommended that you include all mentioned files, especially if you intend to publish it for others.

* README - Provide a general description. If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.
* ChangeLog - Document changes made to each revision.
* LICENSE

=== Functions ===
{| class="wikitable"
!Name
!Returns
!Description
|-
|plugin_PLUGINNAME_info
|array
|Array contains 'name', 'longname', 'version' & 'home_url'
|-
|plugin_PLUGINNAME_init
|void
|Initialize the plugin. Register pages, tabs, triggers, handlers, etc.
|-
|plugin_PLUGINNAME_install
|boolean
|Make any necessary modifications (create tables, create Config settings, etc.)
|-
|plugin_PLUGINNAME_uninstall
|boolean
|Make any necessary modifications (drop tables, delete Config settings, etc.)
|-
|plugin_PLUGINNAME_upgrade
|boolean
|Make any necessary modifications (alter tables, modify Config settings, etc.)
|-
|plugin_PLUGINNAME_HOOKNAME
|varies
|Run when called by a system-level function (described below in the Hooks section)
|}

=== Hooks ===
There are used in cases where custom functions defined by a plugin should be called at specific times.

Examples:
* When resetting or deleting an object
* Resetting the Config settings (Configuration -> User interface)
* Viewing the Data Integrity report

Hooks are already supported in some functions, such as commitResetObject(). If you need it supported by another function, create a GitHub pull request and it will probably be accepted.

=== Upgrades ===
The plugin_PLUGINNAME_upgrade function is mandatory. If this is the first version, or if no upgrade steps are required, simply have the function return TRUE.

There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information. These transitions should be handled by the upgrade function.

Example modeled after the core RackTables upgrader:

<pre>
function plugin_myplugin_upgrade ()
{
$db_info = getPlugin ('myplugin');
$v1 = $db_info['db_version'];
$code_info = plugin_plugin_info ();
$v2 = $code_info['version'];

if ($v1 == $v2)
throw new RackTablesError ('Versions are identical', RackTablesError::INTERNAL);

// find the upgrade path to be taken
$versionhistory = array
(
'1.0',
'2.0',
'3.0'
);
$skip = TRUE;
$path = NULL;
foreach ($versionhistory as $v)
{
if ($skip and $v == $v1)
{
$skip = FALSE;
$path = array();
continue;
}
if ($skip)
continue;
$path[] = $v;
if ($v == $v2)
break;
}
if ($path === NULL or ! count ($path))
throw new RackTablesError ('Unable to determine upgrade path', RackTablesError::INTERNAL);

// build the list of queries to execute
$queries = array ();
foreach ($path as $batchid)
{
switch ($batchid)
{
case '2.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '2.0' WHERE name = 'myplugin'";
break;
case '3.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '3.0' WHERE name = 'myplugin'";
break;
default:
throw new RackTablesError ("Preparing to upgrade to $batchid failed", RackTablesError::INTERNAL);
}
}

// execute the queries
global $dbxlink;
foreach ($queries as $q)
{
try
{
$result = $dbxlink->query ($q);
}
catch (PDOException $e)
{
$errorInfo = $dbxlink->errorInfo();
throw new RackTablesError ("Query: ${errorInfo[2]}", RackTablesError::INTERNAL);
}
}
}
</pre>

Plugins

2017-10-02T16:24:53Z

Infrastation: /* Writing a Plugin */ It was done in 0.21.0, not 0.20.11.

== Warning ==

----

----

----

----

----

'''This page is a part of work in progress, it documents a feature that is not yet in RackTables source code.'''

----

----

----

----

----

== Overview ==
Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.

Note that this guide details features that may or may not be included in a future release.

=== States ===
A plugin may be in one of three states.
* Not installed - it exists in the plugins directory, but hasn't been installed yet
* Enabled - it has been installed and is active
* Disabled - it has been installed and was subsequently disabled

=== Administration ===
To install a plugin, first copy it to the "plugins" directory. Then visit the Configuration -> Plugins page and click the Edit tab. The new plugin should be listed with a state of "Not installed". Click the Install icon.

To upgrade a plugin, first backup the appropriate "plugins" sub-directory. To be safe, it's also a good idea to backup your entire database. Afterwards, copy over the new version into the "plugins" directory. When you visit the Edit tab of the Configuration -> Plugins page, you should see a variance in the Code Version and DB Version columns. Click the Upgrade icon.

== Writing a Plugin ==
The old procedure involves placing a PHP file in the "plugins" directory of your RackTables installation. That method has limited functionality and may be deprecated at a later date.

A new plugin architecture was introduced in version 0.21.0. It includes the ability to install, uninstall, enable and disable plugins from the web interface. It is assumed that each plugin resides in its own directory within the main "plugins" directory, and that each plugin contains a "plugin.php" file which includes certain functions. The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.

=== Files ===
Each plugin is expected to contain certain files. While the only required file is "plugin.php", it is recommended that you include all mentioned files, especially if you intend to publish it for others.

* README - Provide a general description. If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.
* ChangeLog - Document changes made to each revision.
* LICENSE

=== Functions ===
{| class="wikitable"
!Name
!Returns
!Description
|-
|plugin_PLUGINNAME_info
|array
|Array contains 'name', 'longname', 'version' & 'home_url'
|-
|plugin_PLUGINNAME_init
|void
|Initialize the plugin. Register pages, tabs, triggers, handlers, etc.
|-
|plugin_PLUGINNAME_install
|boolean
|Make any necessary modifications (create tables, create Config settings, etc.)
|-
|plugin_PLUGINNAME_uninstall
|boolean
|Make any necessary modifications (drop tables, delete Config settings, etc.)
|-
|plugin_PLUGINNAME_upgrade
|boolean
|Make any necessary modifications (alter tables, modify Config settings, etc.)
|-
|plugin_PLUGINNAME_HOOKNAME
|varies
|Run when called by a system-level function (described below in the Hooks section)
|}

=== Hooks ===
There are used in cases where custom functions defined by a plugin should be called at specific times.

Examples:
* When resetting or deleting an object
* Resetting the Config settings (Configuration -> User interface)
* Viewing the Data Integrity report

Hooks are already supported in some functions, such as commitResetObject(). If you need it supported by another function, create a GitHub pull request and it will probably be accepted.

=== Upgrades ===
The plugin_PLUGINNAME_upgrade function is mandatory. If this is the first version, or if no upgrade steps are required, simply have the function return TRUE.

There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information. These transitions should be handled by the upgrade function.

Example modeled after the core RackTables upgrader:

<pre>
function plugin_myplugin_upgrade ()
{
$db_info = getPlugin ('myplugin');
$v1 = $db_info['db_version'];
$code_info = plugin_plugin_info ();
$v2 = $code_info['version'];

if ($v1 == $v2)
throw new RackTablesError ('Versions are identical', RackTablesError::INTERNAL);

// find the upgrade path to be taken
$versionhistory = array
(
'1.0',
'2.0',
'3.0'
);
$skip = TRUE;
$path = NULL;
foreach ($versionhistory as $v)
{
if ($skip and $v == $v1)
{
$skip = FALSE;
$path = array();
continue;
}
if ($skip)
continue;
$path[] = $v;
if ($v == $v2)
break;
}
if ($path === NULL or ! count ($path))
throw new RackTablesError ('Unable to determine upgrade path', RackTablesError::INTERNAL);

// build the list of queries to execute
$queries = array ();
foreach ($path as $batchid)
{
switch ($batchid)
{
case '2.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '2.0' WHERE name = 'myplugin'";
break;
case '3.0':
// perform some upgrade step here
$queries[] = "UPDATE Plugin SET version = '3.0' WHERE name = 'myplugin'";
break;
default:
throw new RackTablesError ("Preparing to upgrade to $batchid failed", RackTablesError::INTERNAL);
}
}

// execute the queries
global $dbxlink;
foreach ($queries as $q)
{
try
{
$result = $dbxlink->query ($q);
}
catch (PDOException $e)
{
$errorInfo = $dbxlink->errorInfo();
throw new RackTablesError ("Query: ${errorInfo[2]}", RackTablesError::INTERNAL);
}
}
}
</pre>

Main Page

2017-10-02T16:24:13Z

Infrastation: add a link to the plugins page

NewRelease

2017-10-01T20:44:37Z

Infrastation: /* part 2 (unit testing) */ just run express.sh

== pre-release checklist ==
=== part 1 ===
First make sure that all necessary changes are already committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure that <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git status
git add ChangeLog
[...]
git add wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
./tests/express.sh
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* Log into SF shell service:
<pre>
$ cat ~/.ssh/config
Host shell.sourceforge.net
User YOUR_SF_USERNAME,racktables
$ ssh -t shell.sourceforge.net create
# Sometimes the above command doesn't drop you into the newly created session, in this case
# an additional "ssh shell.sourceforge.net" will put you through.
# upon logging in update $lastrelease
$ vim /home/project-web/racktables/htdocs/header.php
# test the "download" link at racktables.org to work
</pre>

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

RackTablesAdminGuide

2017-05-29T11:03:49Z

Infrastation: Live VLANs is obsolete, remove the section.

= User authentication =
Authentication is a way to tell that the remote user is who he or she purports to be. This can be done in three ways, with or without knowing the user's password, and is controlled through an option on the configuration page and via editing parameters in the "secret.php" file in the "inc" folder of your installation. Authentication does not automatically equate to access. All users other than the default "admin" user must be explicitly granted access, either individually, or via group permissions (see the "Permission configuration" section below), as specified under "Configuration: Permissions". If you do not grant access, the user will not be permitted to view any pages. !RackTables traditional account locking works regardless of authentication sources, so one can always disable accounts one by one, if necessary.

== Local authentication ==
This is the oldest (and default) method. Password hashes are stored in SQL database along with all other data. !RackTables checks the passwords itself.

== LDAP authentication ==
Administrator user is the user with user_id 1, which by default maps to username "admin". Administrator is '''always''' authenticated locally via the accounts database. Other user accounts are treated the same way by default, but this can be changed. See [[LDAP | here]] for detailed instructions on configuring RackTables for LDAP.

==external authentication (since 0.17.0)==
In this mode !RackTables only makes sure, that the user is using a username to access. It is assumed, that Apache is configured to authenticate users, in its simplest case:
<pre>
AuthType basic
AuthName "beware ogres"
AuthUserFile /var/www/racktables/.htpasswd
Require valid-user
</pre>
After Apache configuration it is necessary to open !RackTables main page and make sure, that Apache really blocks unauthenticated users, whichever means it uses to validate them (htpasswd, LDAP, Kerberos and so on). Only after that the software configuration must be changed to always trust the username provided (because the web-server has already validated it). This is done in secret.php file:
<pre>
$user_auth_src = 'httpd';
</pre>

===External Authentication with Shibboleth===
RackTables is compatible with [https://wiki.shibboleth.net/confluence/display/SHIB2/Home Shibboleth] authentication. It will require the installation of the Sibboleth Service Provider (SP) module for Apache, and for that to be configured to accept identity assertions from an Identity Provider (IDp), Federation, WAYF service or Directory Service.

Detailed installation instructions for the Shibboleth SP are here: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxInstall

Be sure that RackTables is properly installed and working with the local administrator account (<tt>admin</tt>) before setting up Shibboleth.

* Check that required packages are installed:
<pre>
$ sudo apt-get install libapache2-mod-shib2
</pre>
* Configure <tt>shibd</tt> for your Fedration or IDp (using the instructions above, or those provided by your IDp or Registry)
* Enable the <tt>shibd</tt>
<pre>
$ sudo update-rc.d shibd enable
</pre>
* Enable the Apache modules for Shibboleth and SSL:
<pre>
$ sudo a2enmod ssl
$ sudo a2enmod shib2
</pre>
* Create a SSL secured site for RackTables by createing <tt>/etc/apache2/sites-available/racktables-ssl</tt> with the content:
<pre>
<VirtualHost *:443>
ServerAdmin webmaster@localhost

DocumentRoot /var/www
SSLEngine on
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key

<FilesMatch "\.(cgi|shtml|phtml|php)$">
SSLOptions +StdEnvVars
</FilesMatch>
<Directory /usr/lib/cgi-bin>
SSLOptions +StdEnvVars
</Directory>
# "force-response-1.0" for this.
BrowserMatch "MSIE [2-6]" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
# MSIE 7 and newer should be able to use keepalive
BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown

<Location /racktables>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>
</VirtualHost>
</pre>
* Enable the RackTables site in Apache:
<pre>
$ sudo a2ensite racktables-ssl
</pre>
* Restart Shibboleth and Apache:
<pre>
$ sudo service shibd restart
$ sudo service apache2 restart
</pre>
* Edit <tt>/var/www/racktables/inc/secret.php</tt> and add the following lines:
<pre>
$user_auth_src = 'httpd';
$require_local_account = FALSE;
</pre>
* Use your browser to navigate to your RackTables application using HTTPS (i.e. <tt><nowiki>https://your.server.com/rackspace</nowiki></tt>), you should now be presented with a Shibboleth login from your configured IDp, or Directory service. This should present you with a "Not Authorised" screen, copy the username that Shibboleth has handed RackTables.
* Comment out the lines added to <tt>/var/www/racktables/inc/secret.php</tt> in the previous step:
<pre>
# $user_auth_src = 'httpd';
# $require_local_account = FALSE;
</pre>
* Return to RackSpace in your browser and reload the page, login as the local administrator (<tt>admin</tt>)
* Create a tag to identify RackTables administrators e.g. 'RackTable Admin'
* Create a new user with the username you coped previously, and tag it with the administrator tag
* Edit the RackCode in the '''Configure''' -> '''Permissions''' tool to give your administrator tag access (this also gives non-admins viewing rights), Verify and Save:
<pre>
allow {$userid_1} or {$tab_default}
allow {RackTables Admin}
</pre>
* Log the local administrator out of the RackSpace web application
* Return to <tt>/var/www/racktables/inc/secret.php</tt> and uncomment the lines:
<pre>
$user_auth_src = 'httpd';
$require_local_account = FALSE;
</pre>
* Return to RackSpace in your browser and reload the page. You should now be logged in as your Shibboleth user, and have administrator access.

'''Note:''' Replace the snakeoil certificates in the Apache configuration with certificates issued by a proper Certificate Authority, or use self signed certificates.
'''Note:''' The certificates in the Apache configuration are your Front End certificates presented to the user's browser, they are not the Back End certificates used by Shibboleth to encrypt back-channel communication between a SP and and IDp. '''Do not''' secure Apache with certificates found in <tt>/etc/shibboleth/</tt>
'''Note:''' RackTables does not handle user names with special characters (e.g. '@'), which may prevent the use of <tt>$username=User@company.url.com</tt> rules in RackCode.

== logging out ==
When using external user authentication, special care should be taken to enable logging out of the system. According to HTTP spec, user agent (browser) among other factors uses "authentication realm" to decide, which username and password to send, when requesting each page. When the browser gets HTTP code 401 ("unauthorized"), it resets cached username/password pair for the realm, which is presented in the 401 reply. The "logout" link in !RackTables points to a special location, which always refuses to authenticate, and presents the same realm, which was used for initial authentication. That works fine for local and LDAP authentication, because in both cases the realm comes from the same source. For "httpd" authentication, however, this isn't always true (realms mismatch and cached password isn't reset), so a user often cannot log out by following "logout" link.

To make things working again, it is necessary to make the realm, which Apache presents to the user, match the one, which is seen after following the "logout" link. Let's suppose, you see {{{Snake Oil RackTables access-500}}} after clicking "logout" (500 or other value is often added by Apache PHP module to make things more secure). The setting in htaccess file then should be:
<pre>
AuthName "Snake Oil RackTables access-500"
</pre>
After that it's easy to find, that logging out works again.

== Resetting administrator password (and username) ==
<pre>
mysql> UPDATE UserAccount SET user_name = 'admin', user_password_hash = SHA1('mynewpassword') where user_id = 1;
</pre>

= Failover setup =
RackTables' purpose is to aid in troubleshooting, but sometimes the problem makes !RackTables system unavailable itself. A read-only backup replica of the server will help making through the accident faster. The diagram below explains necessary setup:

[[Image:RackTables-failover.png]]
----

= Vendor sieve (since 0.17.0) =
The dictionary is made of many (hundreds) records, most of them being hardware models. The records are usually grouped by OEM brand or product line. It's common to stick with one particular brand and never purchase others. However, by default all records are shown in drop-down SELECT lists on "Properties" tab of each object. It is possible to hide certain option groups from being rendered by default. To do so, navigate to "Configuration", then to "User interface" and switch to "Change". There is an option (empty by default) named "Vendor sieve configuration". Its format is:
<pre>
Vendor1; Vendor2@X; Vendor3; Vendor4@Y; ...
</pre>

Here VendorZ is what you see in bold in drop-down list (OPTGROUP, to be specific), and X/Y are optional numeric values of object type. If the object type isn't specified, related vendor is screened out from SELECTs for all object types. So, say, one has Sun (tm) tape libraries, but has no Sun (tm) servers. To hide "Sun" OPTGROUP from the list of server models and leave it on the list of tape libraries, he puts the following into option value:
<pre>
Sun@4
</pre>
This way the "HW type" SELECT gets considerably shorter. However, this feature is purely cosmetic: it doesn't remove any data from the SQL database, and doesn't change existing data. If there is a particular server marked as one of Sun (tm) boxes, the record is shown as before and upon going to "Properties" tab the whole "Sun" OPTGROUP is there (because the value is already set). It's possible to change from one Sun model to another in this situation. But once the box is changed to, say, a noname server, the "Sun" OPTGROUP is again gone, as requested by the sieve.
----

= AutoPorts =
When we create objects, we often (if not always) add some ports to them depending on the type and hardware model. Although RackTables can't yet add ports depending on hardware model (except via SNMP), it is (as of 0.14.12 release) able to automatically add ports upon object creation. This process is controlled by AutoPorts configuration string:

<pre><object type1 id>=<n1>*<port type1 id>*<format1>;<object type2 id>=<n2>*<port type2 id>*<format2>+<n3>*<port type3 id>*<format3>;<object type3 id>=<n4>*<port type4 id>*<format4>+<n5>*<port type5 id>*<format5>...</pre>

The default value is "{{{4 = 1*33*kvm + 2*24*eth%u}}}", which makes each new server to have 2 Linux-style GigE ports and 1 KVM port. To make each new PDU bear 6 power plugs in addition to this, the AutoPorts config would be as follows: "<tt>4 = 1*33*kvm + 2*24*eth%u; 2 = 6*16*%02u</tt>". Exact key values can be found on the dictionary page in chapters PortType and RackObjectType (keys are rendered as mouse hints for each dictionary record). The format string is the one accepted by printf family functions and ports are indexed starting from 0 and upwards.

The feature can also make its work later. When you browse an object, which has no ports yet, but could have (according to AutoPorts configuration), you see additional tab named "AutoPorts". It will present you with its idea of which records could be added, and a button to do so. Once you add any ports to an object by automatic or manual mean, the tab will hide itself.
----

= KVM ports =
Since the 0.14.11 release RackTables has 2 distinct port types for physical console: "KVM (host)" and "KVM (console)". Both types more describe the function, than an exact set of connectors. The former one emits video signal and accepts keyboard and/or mice events. The latter one accepts video signal and emits HID events. There's no specification, which mix of DVI, DB15, PS/2, DIN, USB and even Sun connectors is in question for each particular port, hence a variety of cabling and convertors is usually available. One usually just has "console" or "KVM switch" boxes with "KVM (console)" ports and server boxes with "KVM (host)" ports. Then connecting two servers or two pure consoles together wouldn't be possible, as it used to be before.

A known drawback of the new approach is that all the ports (especially connected ones), which were created before the 0.14.11 release, now belong to "KVM (host)" type regardless of their actual function. There are ways to fix this depending on the number of such ports:
* Small: delete and re-add ports manually.
* Average: issue UPDATE SQL statement (backup you data first!).
* Really big: ask for help on the racktables-users mailing list. We might invent an automatic upgrading script.
----

= Fixing the RackCode =
It's possible to write RackCode that locks the administrator out, so you can't fix things the usual way. In most situations you can always log in as administrator and fix things, but it's possible to break even this. The following SQL code restores administrator access:
<pre>
UPDATE Script SET script_text = NULL WHERE script_name = 'RackCodeCache';
UPDATE Script SET script_text = CONCAT('allow {$userid_1} ', script_text) WHERE script_name = 'RackCode';
</pre>
----

= Permission configuration =

If you have issues understanding of how the permissions thing works, try to consider the permissions script as firewall rules.

The current security context (a packet in firewall terms) is sequentially compared to each rule (statement in permissions script), top to bottom. If it matches, the action specified in rule takes place ('''allow''' or '''deny''') and the process stops.

The current context is a set of tags originated from the currently logged-in user, an entity being viewed, and navigation data (current page and tab name). These could be either [[RackTablesUserGuide#Automatic_tags|automatic tags]] or user-assigned tags.

So, the rules like

<pre>allow {$userid_1}
allow {$username_jack}</pre>

unconditionally allow any context containing tags {$userid_1} or {$username_jack}, which makes those users the power- ones.

But the rule

<pre>allow {$username_bill} and {$tab_default}</pre>

allows anything to user named 'bill' when he is on 'default' tab. The default tab never contains controls to modify the DB, so the user has read-only permissions if there are no other allowing rules below.

== More examples ==

'''Note:''' The RackCode saved in the MySQL database contains hidden characters, such as carriage returns and new lines. RackCode edited using the <tt>mysql</tt> command line client or using the [http://wb.mysql.com/ MySQL Workbench client] may not work.

=== Administrator with unlimited access ===
<pre>
allow {$userid_1} # admin is always UID 1 regardless of username
</pre>

=== Admin and power user ===
<pre>
allow {$userid_1}
allow {$username_jack}
</pre>

=== Admin and a group of power users ===
This approach requires creating a tag (Configuration -> Tag tree) named "power user". Then each user account of the group must be tagged with this tag. After that the following code text would do the trick:

<pre>
allow {$userid_1}
allow {power user}
</pre>

This way it's possible to run with the same text, granting and revoking permissions through attaching and removing role tags.

=== Admin, a group of power users and a group of managers ===
RackTables pages have tabs. There is always at least one tab, the "default" one. Its name is always "default" and its contents doesn't allow changing things. It may show data about current items and/or links to other pages, but basically it's read-only. This way, having {$tab_default} on the current security context is equivalent to read-only access. Of course, this setup assumes a role tag for managers accounts.
<pre>
allow {$userid_1} or {power user}
allow {manager} and {$tab_default}
</pre>

=== Admin can write, anyone can read ===
<pre>
allow {$userid_1} or {$tab_default}
</pre>

=== Permitting a user to view his own assets ===
Let's suppose you are setting up !RackTables for a colocation provider. A customer company, Snake Oil Web Services, wants to see what happened to their 20 servers you have accepted for colocation. They would also like to know which server must use which IP address for things to work. You create a user account, "snakeoil", then create a tag "Snake Oil asset" and use it to tag each of that 20 servers. After that the following code permits them what they need and nothing else:
<pre>
allow {$username_snakeoil} and {$tab_default} and {Snake Oil asset}
</pre>
There are things to mention, which aren't obvious:
# The user will be able to access only the pages, which display objects. As long as you use "Snake Oil asset" tag to mark servers only, it will get onto the context only in specific locations. IOW, the "snakeoil" account will not be authorized to view even the main page. For this specific case you can provide them with a list of 20 URLs.
# When you decide to use a more generic description for the tag, it becomes easy to achieve unexpected results with valid permission rules. Say, if you have a "Snake Oil" tag, some hardware and several user accounts, you may decide to tag not only servers, but accounts as well. This will effectively permit every Snake Oil account to access default tab of every page in the system, because of {Snake Oil} being always present on the security context. That's why the example uses {Snake Oil asset} to help things remain separated.

=== Disable log delete for everyone ===
It is usually not desirable to remove log entries (especially accidentally), so you may set this as the ''first'' rule of permissions:
<pre>
deny {$tab_log} and {$op_del}
</pre>

=== Headquarters and branch offices ===

Let's assume having the follwing tag tree:
<pre>
- assets
-- HQ assets
-- HQ managed
-- Arizona assets
-- Texas assets
- admins
-- HQ admins
-- Arizona admins
-- Texas admins
</pre>

Then the following ruleset would allow each branch viewing all, but managing only own assets. Some local stuff could be placed under authority of the headquarters (this stuff would be tagged with 2 tags at a time).
<pre>
allow {admins} and {assets} and {$tab_default}
deny not {HQ admins} and {HQ managed}
allow {Arizona admins} and {Arizona assets}
allow {Texas admins} and {Texas assets}
allow {HQ admins} and ({HQ assets} or {HQ managed})
</pre>

=== Disabling Live PTR ===

If you need to disable the Live PTR functionality, the following steps should be followed.

1. Create a Tag entry for each network you want to disable this functionality for. For example, say there are two networks: "Production" (10.10.0.0/24) and "Office" (10.3.0.0/24), and you only want to disable this functionality on the Production network. You would create a tag called "Production-LAN", then associate the "Production" Network to the "Production-LAN" tag.

2. Go to Configuration > Permissions.

3. Add the below line to the top of the Permissions list and save. (Remember that if you add the deny rule below the allow ones, it won't take affect.)
deny {$tab_liveptr} and {Production-LAN}

4. Navigate to the Production network under IPv4space section. Click the network, and confirm that the "LivePTR" tab is not available.

= Defining a new RackTables Object Type =
(contributed by Craig Hoffman)

[[File:RackTables_CircuitExample.PNG]]

Perhaps you have a piece of equipment that is currently not listed in the default list of RackTables objects. This could be something physical, like an environmental sensor. Or, perhaps, you want to extend RackTables to support something more virtual, like network circuits. (I wanted to have my CircuitDB info in one location. To this end, I created a Rack Row called "Virtual", and a 47U rack called "Circuits". I just stick each of my circuits in there so they don't show up as "Unmounted".)

This process has been discussed from time to time on the mailing list. Here's how you do it:

* From the Main Menu, select Configuration, '''Dictionary''', and then select the dictionary '''"ObjectType"'''.
* Select "Edit" and add the new object type that you wish to create. I extended RackTables to support circuits, so I typed in "Circuit".
Now you need to create a dictionary entry that will be used to tie attributes to.
* From the Main Menu, select Configuration, '''Dictionary''', and then select '''"Manage Chapters"''' at the top. Add a new entry (Circuit ID as my example).
You can now create the attributes that will be assigned to your new dictionary entry. For a circuit, things like circuit ID#, carrier, AS#, contact name, etc. You can always go back and add more attributes as needed.
* From the Main Menu, select Configuration, '''Attributes''', and '''Edit Attributes'''. Create each attribute that you need. Take care in the '''type''' of attribute. "String" is probably what you want, when in doubt.
You're just about done. It's time to assign those new attributes to the dictionary entry.
* From the Main Menu, select Configuration, '''Attributes''', and '''Edit Map'''. Select the new attributes and apply it to the new dictionary entry. You probably do not need to do anything with the third dropdown box, "dictionary chapter...".

Now you should be able to go back to the Main Menu, and create some new objects with your new Object Type.

= Adding new port types =
See [[adding new port types]] page to activate hidden port types or to create new ones.

= Configuring CLI gateways to network devices =

RackTables has some features which need to have CLI access to network devices. Those features are:
<ul>
<li>Live ports (FDB, interface status)
<li>Live neighbors (CDP, LLDP)
<li>802.1Q management
</ul>

RackTables is able to interact with devices through pure TCP terminal session (netcat), telnet or ssh.
The administrator is responsible for configuring the protocol, connection options and authentication credentials used to connect to particular devices.

To do so, administrator must include the function terminal_settings into secret.php.

The minimal example of such function:
<pre>
function terminal_settings ($cell, $params)
{
$params[0]['username'] = 'login';
$params[0]['password'] = 'password';
}
</pre>

The defaults of $params[0] array are pretty reasonable, and the only keys which are absolutely needed to be set are 'usermame', 'password' (for netcat or telnet), and 'sudo_user'/'identity_file' (for ssh).

More comprehensive example might look like this:
<pre>
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
{
$params[0]['protocol'] = 'ssh';
$params[0]['proto'] = '4';
$params[0]['sudo_user'] = 'racktables';
$params[0]['connect_timeout'] = 2;
}
elseif (considerGivenConstraint ($cell, '{Switch}'))
{
$params[0]['username'] = 'racktables';
$params[0]['password'] = 'password';
$params[0]['timeout'] = 60;
}

if (considerGivenConstraint ($cell, '{$attr_4_251}')) // IOS 12.1
$params[0]['protocol'] = 'telnet';
</pre>

The possible keys in $params[0] can be determined by calling print_r ($params[0]).

To make the remote gateways features work for a particular device, the following conditions should be met:
<ul>
<li>FQDN field of object is set to DNS name or IP address of device
<li>SW type field of object is set and supported by particular gateway feature
<li>terminal_settings function defined in secret.php
</ul>

= File uploads =
There are several settings in php.ini which you may need to modify:
;file_uploads
: needs to be On
;upload_max_filesize
: max size for uploaded files
;post_max_size
: max size of all form data submitted via POST (including files)
The following MySQL server parameter may be relevant too:
;max_allowed_packet

= Troubleshooting =

Adding the following parameter to "secret.php" will enable debugging, which is helpful in tracking down permissions errors (for example).

<pre>
$debug_mode= 1;
</pre>

Make sure you disable this by commenting it out or deleting it when you're done debugging! :)

Main Page

2017-05-17T19:26:19Z

Infrastation: use the 2017Q2 roadmap image

[[File:RackTables-development-roadmap-2017Q2.png|535px|thumb|right]]
* for RackTables users
** The [https://github.com/RackTables/racktables/blob/maintenance-0.20.x/README.md README file] now replaces the old Installation HOWTO.
** [[RackTablesAdminGuide | Administrator's guide]]
** [[RackTablesUserGuide | User's guide]]
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)
** [[FAQ]]
** [[LDAP | LDAP authentication]]
** [[SAML | SAML authentication]]
* for RackTables hackers
** [[SourceCode | Working with RackTables source code]]
** [[RackTablesDevelGuide | Developer's guide]]
** [[FeatureWishlist | Feature wishlist]]
** [[Gateways | Extending RackTables with gateways]]
* for development team
** [[NewRelease | Checklist and procedures to make a new release]]
** [[ProjectInfrastructure | Project infrastructure]]
** [[Roadmap]]

To use this site over an SSL connection, visit [https://wiki.racktables.org/ https://wiki.racktables.org/]

File:RackTables-development-roadmap-2017Q2.png

2017-05-17T14:53:53Z

Infrastation:

NewRelease

2017-05-12T13:21:51Z

Infrastation: /* updating the main web-site */ add a comment

== pre-release checklist ==
=== part 1 ===
First make sure that all necessary changes are already committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure that <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git status
git add ChangeLog
[...]
git add wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
phpunit
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* Log into SF shell service:
<pre>
$ cat ~/.ssh/config
Host shell.sourceforge.net
User YOUR_SF_USERNAME,racktables
$ ssh -t shell.sourceforge.net create
# Sometimes the above command doesn't drop you into the newly created session, in this case
# an additional "ssh shell.sourceforge.net" will put you through.
# upon logging in update $lastrelease
$ vim /home/project-web/racktables/htdocs/header.php
# test the "download" link at racktables.org to work
</pre>

=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

NewRelease

2017-05-12T13:11:37Z

Infrastation: /* producing and publishing deliverables */ add minor clarifications

== pre-release checklist ==
=== part 1 ===
First make sure that all necessary changes are already committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure that <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git status
git add ChangeLog
[...]
git add wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
phpunit
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* Log into SF shell service:
<pre>
$ cat ~/.ssh/config
Host shell.sourceforge.net
User YOUR_SF_USERNAME,racktables
$ ssh -t shell.sourceforge.net create
# upon logging in update $lastrelease
$ vim /home/project-web/racktables/htdocs/header.php
# test the "download" link at racktables.org to work
</pre>
=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>

NewRelease

2017-05-11T16:44:34Z

Infrastation: /* part 1 */ specify a missing argument

== pre-release checklist ==
=== part 1 ===
First make sure that all necessary changes are already committed into the repository:
<ul>

<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:
<pre>
git status
</pre>
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>

<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>

<li>Make sure that <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>

<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>

<li>Produce a commit with all changes pending thus far:
<pre>
git status
git add ChangeLog
[...]
git add wwwroot/inc/config.php
git commit
</pre>
</li>

<li>Check the source code out from the same branch to a '''clean location''' to test it.
<pre>
git clone git@github.com:RackTables/racktables.git
cd racktables
git checkout master # or maintenance
</pre></li>

<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
<pre>
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre></li>

<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
<pre>
mysql racktables_db < scripts/init-sample-racks.sql
</pre></li>

<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
<pre>
# reload using the previous release
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
# (make through upgrade.php)
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
</pre></li>

=== part 2 (unit testing) ===
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''

<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li>
<pre>
DROP DATABASE IF EXISTS racktables_unittest;
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
</pre>

<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>

<li>Load the sample data.</li>
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>

<li>Export the database to the tests/data dir.</li>
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>

<li>Run the unit tests. Fix any failures.</li>
<pre>
cd tests
phpunit
</pre>

<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>

=== part 3 (finalization) ===
<li>Test the source by hand as much as you find possible.</li>

<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>

<li>Do not proceed further until everything is fixed consistently.</li>
</ul>

== the release itself ==
<pre>
git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z
</pre>

== rolling out ==
=== producing and publishing deliverables ===
* Make two archives:
<pre>
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer).
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded tar.gz as "current".
** Open properties form (round "(i)" sign) of the previous release tar.gz.
** Unset all "default download for" checkboxes.
** Unset "download button" text.
** Save.
** Open properties form (round "(i)" sign) of the previous release zip.
** Unset Windows "default download for" checkbox.
** Unset "download button" text.
** Save.
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.
** Set "download button" text to "latest stable".
** Save.
** In the latest zipfile properties form, set Windows "default download for" checkbox.
** Set "download button" text to "latest stable".
** Save.
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).

=== updating Mantis ===
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.

=== updating the main web-site ===
* Log into SF shell service:
<pre>
$ cat ~/.ssh/config
Host shell.sourceforge.net
User YOUR_SF_USERNAME,racktables
$ ssh -t shell.sourceforge.net create
# upon logging in update $lastrelease
$ vim /home/project-web/racktables/htdocs/header.php
# test the "download" link at racktables.org to work
</pre>
=== updating other news feeds ===
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
* Update IRC channel topic

=== updating demo ===
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
** <tt>git commit; git push</tt>
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
<pre>
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
</pre>