From: kkalev Date: Mon, 27 Oct 2003 12:46:25 +0000 (+0000) Subject: * Add a HOWTO from Paris Stamatopoulos X-Git-Url: https://git.entuzijast.net/?a=commitdiff_plain;h=4289fc0b0bc92c492fcf13c822d8f275944dfbfb;p=freeradius-dialup-admin.git * Add a HOWTO from Paris Stamatopoulos * create a doc directory and move the documentation files there --- diff --git a/Changelog b/Changelog index 8d5905a..83ef7df 100644 --- a/Changelog +++ b/Changelog @@ -16,6 +16,8 @@ Ver 1.65: * Also take the Session-Timeout in consideration when calcualting the remaining time in user_admin.php3 * Add regex matching in log_badlogins and don't expect the callerid to always be in numeric format * Small html corrections in user_toolbar.html.php3 +* Add a HOWTO from Paris Stamatopoulos +* create a doc directory and move the documentation files there Ver 1.63: * Do an eval on the attribute description strings in the user_edit page. That will allow the login-time creation page to work properly. diff --git a/AUTHORS b/doc/AUTHORS similarity index 100% rename from AUTHORS rename to doc/AUTHORS diff --git a/FAQ b/doc/FAQ similarity index 100% rename from FAQ rename to doc/FAQ diff --git a/HELP_WANTED b/doc/HELP_WANTED similarity index 100% rename from HELP_WANTED rename to doc/HELP_WANTED diff --git a/doc/HOWTO b/doc/HOWTO new file mode 100644 index 0000000..106d05d --- /dev/null +++ b/doc/HOWTO @@ -0,0 +1,601 @@ + +Dialup Admin HOWTO +------------------ + +Version 0.1 Sun Oct 26 04:03:00 EET 2003 + + +1. Installation + 1.1 Obtaining Dialup Admin + 1.2 Prerequisities + 1.3 Installing & System Configuration + 1.3.1 Unpacking & Installation + 1.3.2 Apache Configuration + 1.3.2.1 Enabling PHP Support On Apache + 1.3.2.2 Creating a more secure web interface + 1.3.3 Creating the mySQL Tables + +2. Configuration + 2.1 Configuration Options + 2.1.1 General Options + 2.1.2 Realms Options + 2.1.3 LDAP/SQL Options + 2.1.4 NAS Quering + 2.1.5 Test Variables + 2.1.6 Encryption Methods + 2.1.7 NAS Informations + 2.1.8 LDAP Options + 2.1.9 SQL Options + 2.1.10 Limits Timers + 2.1.11 Various Options + 2.2 The bin/ scripts + 2.2.1 The snmpfinger script + 2.2.2 The log_badlogins script + 2.3 User Attributes + 2.4 Finishing Off + + +3. Troubleshooting + 3.1 When I try to access some page I see the php code instead of html + 3.2 When an attribute contains double (") or single (') quotes + something goes wrong + 3.3 Even though I have uncommented Dialup-Access in user_edits.attrs, + when editing a user, that field is not available... + 3.4 Why do the personal information fields show multiple entries for + attributes like name, department, etc in the user_admin page? + 3.5 After I make a few changes in one of the configuration files + things only work like they worked before + 3.6 It is still not working + +4. HOWTO Information + +1. Installation +--------------- + +This section will take you step by step to create system suitable for +dialup admin to run properly. + + +[1.1] Obtaining Dialup Admin + +There are three ways to obtain the dialup admin package. + +Either download the latest FreeRadius package which most likely contains +the latest dialup admin available. The FreeRadius Package can be obtained +through ftp://ftp.freeradius.org/pub/radius/freeradius-0.9.2.tar.gz +which is the current FreeRadius package at the time of writting. + +Dialup Admin has it's own web page hosted at Sourceforge at +http://sourceforge.net/projects/dialup-admin/ + +Finally one could get the cvs version of Dialup Admin by issuing the +following commands: + +shell> cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/dialup-admin login + +* When prompted for a password simply press the Enter Key + +shell> cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/dialup-admin co dialup_admin + +[1.2] Prerequisities + +Dialup Admin requires the following in order to have full functionality: +o PHP Obtained at: http://www.php.net +o Date::Manip Perl Module Obtained at: http://www.cise.ufl.edu/~sbeck/ + +[1.3] Installing & System Configuration + +At this point we presume that either you have successfully installed PHP and +Date::Manip Perl Module or that your distribution has came with both of them +precompiled and already installed. + +[1.3.1] Unpacking and installation + +In order to install the dialup admin first of all the package must be +uncompressed presuming that we have it in a .tar.gz format and be placed +at a certain directory at the system +(Could be anything, we use /usr/local/dialup_admin) + +shell> tar xfvz dialup_admin-X.XX.tar.gz +shell> mv dialup_admin /usr/local + +The dialup admin contains a number of directories necessary for the program +to operate. Let's concentrate on the htdocs directory. This directory +contains the php scripts needed. In order to have it accessable through +our web server we must set a symbolic link between the two locations. +We presume that the DefaultRoot of the Apache Web Server is /var/www/htdocs + +shell> ln -s /usr/local/dialup_admin/htdocs /var/www/htdocs/dialup + +[1.3.2] Apache Configuration + +[1.3.2.1] Enabling PHP Support on Apache + +Apache must be configured to execute PHP scripts. In order to do so locate +the httpd.conf file (for Slackware Linux this is /etc/apache). We must +enter the following lines inside the httpd.conf + +LoadModule php4_module libexec/libphp4.so +AddModule mod_php4.c +AddType application/x-httpd-php .php +AddType application/x-httpd-php .php3 # This is most important since many of the PHP scripts of Dialup Admin have this extension + +[1.3.2.2] Creating a more secure web interface. + +Since dialup admin does not come with any kind of administrators authorisation +of its own it would be safe to protect this ourselves. + +Add the following to your httpd.conf file: + + + AuthName "Restricted Area" + AuthType Basic + AuthUserFile /var/www/.htpasswd + require valid-user + + +Changing of course the directory path to match yours as well as the +AuthUserFile argument to point to the place where the usernames/passwords +are stored. + +In order to create the htpasswd file the htpasswd utility is required +(It is provided with the apache web server) + +Let's create our first user: + +shell> htpasswd -c /var/www/.htpasswd -m administrator password + +Note: The -c argument should not be used from that point on since it creates + a new password file. + +On the next restart of apache the dialup/ directory is only accessable by a +username/password verification which in our case is administrator:password + +At this point when we connect to the url http://localhost/dialup we should +see the Dialup Admin pages + +[1.3.3] Creating the mySQL tables + +In order to have dialup admin work to the maximum you should create a few +tables in your mySQL. We assume at this point you have a fair ammount of mySQL +knowledge and have a mySQL running somewhere on your network. + +First of all you should create a database for all the tables to be stored into +it. We will call this radius. + +shell> mysql -h mysql.host.com -u username -p + +mysql> CREATE DATABASE radius; +mysql> exit + +At dialup_admin/sql there are four files containg the SQL command to create +the required tables. This is done as follows: + +shell> mysql -h mysql.host.com -u username -p radius < badusers.sql +shell> mysql -h mysql.host.com -u username -p radius < mtotacct.sql +shell> mysql -h mysql.host.com -u username -p radius < totacct.sql +shell> mysql -h mysql.host.com -u username -p radius < userinfo.sql + +NOTE: Remember we named our database "radius". Have you named it somewhat + different replace the "radius" argument on the above commands with + the name you used + +2. Configuration +---------------- + +This is the most important part of this document since the configuration must +match your needs. +The configuration file is located at dialup_admin/conf/admin.conf +However due to the fact that i haven't work with LDAP there are no +documentations regarding this issue. Any contributions are welcome. + +[2.1] Configuration Options + +A few variables must be set to the correct values in order for dialup admin +to work. + + +[2.1.1] General Options + + +General configuration options + +> general_base_dir: /usr/local/dialup_admin + +This is the location where we have installed dialup admin. +Refer to section 1.3.1 for more information + +> general_radiusd_base_dir: /usr/local/bin + +This is the location where the radiusd binary and various radius +related programs resides. Check where FreeRadius has been installed + +> general_domain: domain.gr + +Set the domain name of your network. + + +[2.1.2] Realms Options + + +For more informations on realms consult the documentations provided +with FreeRadius under the doc/ directory + +> general_strip_realms : yes + +Should Dialup Admin strip the realm from the username when displaying this? +Values: Yes / No (Default Yes) + +> general_realm_delimiter: @ + +The delimiter used in realms. Default is @ + +> general_realm_format: suffix + +The format of the realms. Can be either suffix (realm is after the username) +or prefix (realm is before the username). Default is suffix + + +[2.1.3] LDAP/SQL Options + + +Options that specifies the way dialup admin handles users. SQL or LDAP + +> general_lib_type: sql + +This can have as values either ldap or sql. Since I haven't worked with LDAP +we stick with the 'sql' argument + +For the following values there shouldn't be any need for changes + +> general_ldap_attrmap: /etc/raddb/ldap.attrmap +> general_sql_attrmap: %{general_base_dir}/conf/sql.attrmap +> general_extra_ldap_attrmap: %{general_base_dir}/conf/extra.ldap-attrmap +> general_user_edit_attrs_file: %{general_base_dir}/conf/user_edit.attrs +> general_sql_attrs_file: %{general_base_dir}/conf/sql.attrs +> general_default_file: %{general_base_dir}/conf/default.vals + + +[2.1.4] NAS Quering + + +In general the nas quering provides the dialup admin with information +regarding the Online Users. + +> general_finger_type: snmp + +What should be the default quering method of the nas. + +> general_snmpfinger_bin: %{general_base_dir}/bin/snmpfinger + +This probably does not need to be changed + +> general_radclient_bin: /usr/local/bin/radclient + +Must point to the radclient binary + + +[2.1.5] Test Variables + + +The following variables which are self explained are being used while the +"Check Server" button is being pressed to verify that the radius server +is working. The username and password must be of a valid dialup account + +> general_test_account_login: dummy +> general_test_account_password: dummy_password + +> general_radius_server: localhost + +The hostname where the FreeRadius Server runs + +> general_radius_server_port: 1645 + +The port that FreeRadius uses on the hostname + +> general_radius_server_auth_proto: chap + +The method of connecting. Could be either 'chap' or 'pap' + +> general_radius_server_secret: secret_password + +The secret of the server that dialup admin should use while connecting. + +NOTE: You must have a correct entry in clients.conf for the host running + the dialup admin. For more information consult the documentations + that come with FreeRadius + +> general_auth_request_file: %{general_base_dir}/conf/auth.request + +The file conf/auth.request contains the options passed while the +authentification is performed. Should you need to add anything edit this file + + +[2.1.6] Encryption Method + + +> general_encryption_method: md5 + +How the passwords of the users are stored (or should be) in the database. +Could be 'clear', 'md5', 'des'. See Also Section 2.1.9 + + +[2.1.7] NAS Information + + +> nas1_name: host.%{general_domain} + +The name of the NAS. Only the host must be replaced to match yours, +provided that the nas are on the general_domain specified above + +> nas1_model: Lucent + +The model of the NAS. + +> nas1_ip: 10.0.0.1 + +The IP of the NAS + +> nas1_port_num: 120 + +The port number to connect to on the NAS + +> nas1_community: community string + +The community string used by the nas for queries via snmp + +> nas1_finger_type: snmp + +The finger type for the specific nas. Comment out to use the +general_finger_type from above. + + +[2.1.8] LDAP Options + + +Due to insufficient experience no information on LDAP configuration +is provided. + + +[2.1.9] SQL Options + +> sql_type: mysql + +The type of the database. Currenty dialup admin support mySQL ('mysql') +and PostgreSQL('pg') + +> sql_server: localhost +> sql_port: 3306 +> sql_username: radius +> sql_password: XXXXX + +Information regargind the SQL database such as hostname, port, +username and password to be used for connection + +NOTE: The default port for mySQL is 3306 while for PostgreSQL is 5432. + The Username and password are ones set in the database. Creating a + new username is behond the scope of this documentation. + +> sql_database: radius + +The database where all our tables are stored. Read section 1.3.3 + +> sql_accounting_table: radacct +> sql_check_table: radcheck +> sql_groupcheck_table: radgroupcheck +> sql_groupreply_table: radgroupreply +> sql_reply_table: radreply + +The above tables are the ones used also directly through FreeRadius. +The SQL file containing the way to create these tables are at +freeradius-x.x.x/src/modules/rlm_sql/drivers/rlm_sql_/db_.sql + +For more information consult the documentation of FreeRadius + +> sql_badusers_table: badusers +> sql_user_info_table: userinfo +> sql_usergroup_table: usergroup +> sql_total_accounting_table: totacct + +These are the tables created during section 1.3.3. +There shouldn't be any need to change those + +> sql_use_user_info_table: true +> sql_use_operators: true + +Could be true or false + +> sql_default_user_profile: DEFAULT + +Set this to the value of the default_user_profile in your sql.conf if +that one is set. If it is not set leave blank or commented out + +> sql_password_attribute: User-Password + +The password attribute. Should be User-Password if encryption method +is clear (See section 2.1.6) or Crypt-Password if either md5 or des is choosed + +> sql_date_format: Y-m-d +> sql_full_date_format: Y-m-d H:i:s + +The date format + +> sql_row_limit: 40 + +The row limit used in the accounting page in order to limit the output + +> sql_connect_timeout: 3 +> sql_extra_servers: sql2.company.com sql3.company.com + +The above options are used by bin/log_badlogins (See Section 2.x.x) + +> sql_debug: false + +Set to true to enable SQL debugging + +> sql_use_http_credentials: no + +If set to yes then the HTTP credentials (http authentication) will be used +to connect to the sql server instead of sql_username and sql_password. +That way multiple admins with different rights on the sql database can +connect through one dialup_admin interface. + + +[2.1.10] Limits Timers + +> counter_default_daily: 14400 +> counter_default_weekly: 72000 +> counter_default_monthly: none + +The dialup limit displayed on the Dialup Admin. Set to none for no limit + + +[2.1.11] Various Options + + +> general_accounting_info_order: desc + +Can be either asc (older dates first) or desc (recent dates first) + +> general_stats_use_totacct: no + +Use the totacct table for statistics + +> general_use_session: yes + +Set it to yes to use sessions and cache the various mappings You can also +set use_session = 1 in config.php3 to also cache the admin.conf + +NOTE: Remember to use the 'Clear Cache' page if you use sessions and + do any changes in any of the configuration files. + +> general_most_recent_fl: 30 + +This is used by the failed logins page. It states the default back time +in minutes. + +> general_prefered_lang: el +> general_prefered_lang_name: Greek + +It can be default or whatever language. Only greek are supported from +non latin alphabet languages. These attribute only apply for ldap not for sql + +> general_charset: iso-8859-1 + +The charset which will be added as a meta tag in all pages + +> general_decode_normal_attributes: no + +Uncomment this if normal attributes (not the ;lang-xx ones) in ldap +are utf8 encoded. + + +[2.2] The bin/ scripts + + +[2.2.1] The snmpfinger script + +This script make an snmp request to the nas server to retrieve +the online users directly from the NAS and is being used by dialup admin +when general_finger_type: snmp is set. (See section 2.1.4). + +You also must have installed the net-snmp package obtained at +http://www.net-snmp.org + +The snmpfinger script must be edited in order to point to the correct +snmpwalk binary. + +Edit the line $SNMPWALK="/usr/local/bin/snmpwalk"; to represent the location +of snmpwalk binary + +Besides that the snmpfinger uses MIBs only for the CISCO XXXX NAS which may +not work if your NAS is different. For example the mib for a Lucent MAX 3000 +NAS is .1.3.6.1.4.1.529.10.4.1.12 and should also be replaced. + +However the snmpfinger is not actually required if your accounting +is working properly + +[2.2.2] The log_badlogins scripts + +The log_badlogins scripts actually does a tail -f to the radius.log and +intercepts any authentification failure and passes it to the database. +If you are interested in having the Failed Logins on the Dialup Admin +you should execute it once like this: + +bin/log_badlogins /var/log/radius/radius.log /usr/local/dialup_admin/conf/admin.conf& + +Of cource the proper file locations must be set + + +[2.3] User Attributes + +First of all check conf/user_edit.atts and see if the attribute you are +interested in is commented out. If it is just enable it by uncommenting it. +If the attribute is not included in the file add it. +If you use SQL check conf/sql.attrmap. +If you use LDAP check ${freeradius_install_dir}/etc/raddb/ldap.attrmap +and check if the attribute is included in the attribute mapping. + +If it is not then add it there also.Everything should work ok after that. + +[2.4] Finishing + +The above sections should propably have brought you to a working dialup admin. +Note however that if you are interested in logging the failed logins +(See section 2.3.2) you should execute the the log_badlogins each time +the system starts. + + +3. Troubleshooting +-------------------------- + +[3.1] When I try to access some page I see the php code instead of html + +See section 1.3.2.1 + +[3.2] When an attribute contains double (") or single (') quotes + something goes wrong + +Make sure that magic quotes in PHP are turned off + +[3.3] Even though I have uncommented Dialup-Access in user_edits.attrs, + when editing a user, that field is not available... + +...Is this because in sql.attrmap +I have: + +checkItem Dialup-Access none + +What should the attribute be? + +Dialup-Access is an attribute used by the ldap module. It is not implemented in the sql module, that's why the mapping is set to none. +You could set Auth-Type to Reject instead. + +[3.4] Why do the personal information fields show multiple entries for + attributes like name, department, etc in the user_admin page? + +Set general_prefered_lang to en + +[3.5] After I make a few changes in one of the configuration files things + only work like they worked before + +If you are using sessions then remember to use the 'Clear Cache' page after +making any changes. See Section 2.1.11 + +[3.6] It is still not working + +Check that the register_globals in php.ini is set to on. As of PHP 4.2.0 +this is set to off by default. The latest versions of dialup_admin will work +even if register_globals is set to off if the php version is > 4.1.0 +(Thanks to Evren Yurtesen for the suggestion). + +In latest versions you can also enable sql debug (sql_debug: true) +and ldap debug (ldap_debug: true) + + +4. HOWTO Information +--------------------------------- + +This document is distributed under the terms of the GPL (GNU Public License). +Paris Stamatopoulos + diff --git a/TODO b/doc/TODO similarity index 100% rename from TODO rename to doc/TODO