Difference between revisions of "Freeside:1.7:Documentation:Developer/FS/svc acct"

Latest revision as of 13:03, 23 July 2009

NAME

FS::svc_acct - Object methods for svc_acct records

SYNOPSIS

 use FS::svc_acct;

 $record = new FS::svc_acct \%hash;
 $record = new FS::svc_acct { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

 $error = $record->suspend;

 $error = $record->unsuspend;

 $error = $record->cancel;

 %hash = $record->radius;

 %hash = $record->radius_reply;

 %hash = $record->radius_check;

 $domain = $record->domain;

 $svc_domain = $record->svc_domain;

 $email = $record->email;

 $seconds_since = $record->seconds_since($timestamp);

DESCRIPTION

An FS::svc_acct object represents an account. FS::svc_acct inherits from FS::svc_Common. The following fields are currently supported:

svcnum - primary key (assigned automatcially for new accounts); username; _password - generated if blank; sec_phrase - security phrase; popnum - Point of presence (see FS::svc_acct_pop); uid; gid; finger - GECOS; dir - set automatically if blank (and uid is not); shell; quota - (unimplementd); slipip - IP address; seconds -; upbytes -; downbytes -; totalbytes -; domsvc - svcnum from svc_domain; radius_Radius_Attribute - Radius-Attribute (reply); rc_Radius_Attribute - Radius-Attribute (check)

METHODS

new HASHREF

Creates a new account. To add the account to the database, see "insert".

search_sql STRING

Class method which returns an SQL fragment to search for the given string.

label [ END_TIMESTAMP [ START_TIMESTAMP ] ]

Returns the "username@domain" string for this account.

END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.

label_long [ END_TIMESTAMP [ START_TIMESTAMP ] ]

Returns a longer string label for this acccount ("Real Name <username@domain>" if available, or "username@domain").

END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.

insert [ , OPTION => VALUE ... ]

Adds this account to the database. If there is an error, returns the error, otherwise returns false.

The additional fields pkgnum and svcpart (see FS::cust_svc) should be defined. An FS::cust_svc record will be created and inserted.

The additional field usergroup can optionally be defined; if so it should contain an arrayref of group names. See FS::radius_usergroup.

The additional field child_objects can optionally be defined; if so it should contain an arrayref of FS::tablename objects. They will have their svcnum fields set and will be inserted after this record, but before any exports are run. Each element of the array can also optionally be a two-element array reference containing the child object and the name of an alternate field to be filled in with the newly-inserted svcnum, for example [ $svc_forward, 'srcsvc' ]

Currently available options are: depend_jobnum

If depend_jobnum is set (to a scalar jobnum or an array reference of jobnums), all provisioning jobs will have a dependancy on the supplied jobnum(s) (they will not run until the specific job(s) complete(s)).

(TODOC: FS::queue and freeside-queued)

(TODOC: new exports!)

delete

Deletes this account from the database. If there is an error, returns the error, otherwise returns false.

The corresponding FS::cust_svc record will be deleted as well.

(TODOC: new exports!)

replace OLD_RECORD

Replaces OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.

The additional field usergroup can optionally be defined; if so it should contain an arrayref of group names. See FS::radius_usergroup.

queue_fuzzyfiles_update

Used by insert & replace to update the fuzzy search cache

suspend

Suspends this account by calling export-specific suspend hooks. If there is an error, returns the error, otherwise returns false.

Called by the suspend method of FS::cust_pkg (see FS::cust_pkg).

unsuspend

Unsuspends this account by by calling export-specific suspend hooks. If there is an error, returns the error, otherwise returns false.

Called by the unsuspend method of FS::cust_pkg (see FS::cust_pkg).

cancel

Called by the cancel method of FS::cust_pkg (see FS::cust_pkg).

If the auto_unset_catchall configuration option is set, this method will automatically remove any references to the canceled service in the catchall field of svc_domain. This allows packages that contain both a svc_domain and its catchall svc_acct to be canceled in one step.

check

Checks all fields to make sure this is a valid service. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.

Sets any fixed values; see FS::part_svc.

_check_system

Internal function to check the username against the list of system usernames from the system_usernames configuration value. Returns true if the username is listed on the system username list.

_check_duplicate

Internal function to check for duplicates usernames, username@domain pairs and uids.

If the global_unique-username configuration value is set to username or username@domain, enforces global username or username@domain uniqueness.

In all cases, check for duplicate uids and usernames or username@domain pairs per export and with identical svcpart values.

radius

Depriciated, use radius_reply instead.

radius_reply

Returns key/value pairs, suitable for assigning to a hash, for any RADIUS reply attributes of this record.

Note that this is now the preferred method for reading RADIUS attributes - accessing the columns directly is discouraged, as the column names are expected to change in the future.

radius_check

Returns key/value pairs, suitable for assigning to a hash, for any RADIUS check attributes of this record.

Note that this is now the preferred method for reading RADIUS attributes - accessing the columns directly is discouraged, as the column names are expected to change in the future.

snapshot

This method instructs the object to "snapshot" or freeze RADIUS check and reply attributes to the current values.

forget_snapshot

This methos instructs the object to forget any previously snapshotted RADIUS check and reply attributes.

domain [ END_TIMESTAMP [ START_TIMESTAMP ] ]

Returns the domain associated with this account.

END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.

svc_domain

Returns the FS::svc_domain record for this account's domain (see FS::svc_domain).

cust_svc

Returns the FS::cust_svc record for this account (see FS::cust_svc).

email [ END_TIMESTAMP [ START_TIMESTAMP ] ]

Returns an email address associated with the account.

END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.

acct_snarf

Returns an array of FS::acct_snarf records associated with the account. If the acct_snarf table does not exist or there are no associated records, an empty list is returned

decrement_upbytes OCTETS

Decrements the upbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

increment_upbytes OCTETS

Increments the upbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

decrement_downbytes OCTETS

Decrements the downbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

increment_downbytes OCTETS

Increments the downbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

decrement_totalbytes OCTETS

Decrements the totalbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

increment_totalbytes OCTETS

Increments the totalbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

decrement_seconds SECONDS

Decrements the seconds field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

increment_seconds SECONDS

Increments the seconds field of this record by the given amount. If there is an error, returns the error, otherwise returns false.

recharge HASHREF

 Increments usage columns by the amount specified in HASHREF as
 column=>amount pairs.

is_rechargeable

Returns true if this svc_account can be "recharged" and false otherwise.

seconds_since TIMESTAMP

Returns the number of seconds this account has been online since TIMESTAMP, according to the session monitor (see FS::Session).

TIMESTAMP is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

seconds_since_sqlradacct TIMESTAMP_START TIMESTAMP_END

Returns the numbers of seconds this account has been online between TIMESTAMP_START (inclusive) and TIMESTAMP_END (exclusive), according to an external SQL radacct table, specified via sqlradius export. Sessions which started in the specified range but are still open are counted from session start to the end of the range (unless they are over 1 day old, in which case they are presumed missing their stop record and not counted). Also, sessions which end in the range but started earlier are counted from the start of the range to session end. Finally, sessions which start before the range but end after are counted for the entire range.

TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

attribute_since_sqlradacct TIMESTAMP_START TIMESTAMP_END ATTRIBUTE

Returns the sum of the given attribute for all accounts (see FS::svc_acct) in this package for sessions ending between TIMESTAMP_START (inclusive) and TIMESTAMP_END (exclusive).

TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

get_session_history TIMESTAMP_START TIMESTAMP_END

Returns an array of hash references of this customers login history for the given time range. (document this better)

last_login_text

Returns text describing the time of last login.

get_cdrs TIMESTAMP_START TIMESTAMP_END [ 'OPTION' => 'VALUE ... ]; radius_groups

Returns all RADIUS groups for this account (see FS::radius_usergroup).

clone_suspended

Constructor used by FS::part_export::_export_suspend fallback. Document better.

clone_kludge_unsuspend

Constructor used by FS::part_export::_export_unsuspend fallback. Document better.

check_password

Checks the supplied password against the (possibly encrypted) password in the database. Returns true for a successful authentication, false for no match.

Currently supported encryptions are: classic DES crypt() and MD5

crypt_password [ DEFAULT_ENCRYPTION_TYPE ]

Returns an encrypted password, either by passing through an encrypted password in the database or by encrypting a plaintext password from the database.

The optional DEFAULT_ENCRYPTION_TYPE parameter can be set to crypt (classic UNIX DES crypt), md5 (md5 crypt supported by most modern Linux and BSD distrubtions), or (eventually) blowfish (blowfish hashing supported by OpenBSD, SuSE, other Linux distibutions with pam_unix2, etc.). The default encryption type is only used if the password is not already encrypted in the database.

ldap_password [ DEFAULT_ENCRYPTION_TYPE ]

Returns an encrypted password in "LDAP" format, with a curly-bracked prefix describing the format, for example, "{CRYPT}94pAVyK/4oIBk" or "{PLAIN-MD5}5426824942db4253f87a1009fd5d2d4f".

The optional DEFAULT_ENCRYPTION_TYPE is not yet used, but the idea is for it to work the same as the /crypt_password method.

domain_slash_username

Returns $domain/$username/

virtual_maildir

Returns $domain/maildirs/$username/

SUBROUTINES

send_email

This is the FS::svc_acct job-queue-able version. It still uses FS::Misc::send_email under-the-hood.

check_and_rebuild_fuzzyfiles; rebuild_fuzzyfiles; all_username; append_fuzzyfiles USERNAME; radius_usergroup_selector GROUPS_ARRAYREF [ SELECTNAME ]; reached_threshold

Performs some activities when svc_acct thresholds (such as number of seconds remaining) are reached.

BUGS

The $recref stuff in sub check should be cleaned up.

The suspend, unsuspend and cancel methods update the database, but not the current object. This is probably a bug as it's unexpected and counterintuitive.

radius_usergroup_selector? putting web ui components in here? they should probably live somewhere else...

insertion of RADIUS group stuff in insert could be done with child_objects now (would probably clean up export of them too)

SEE ALSO

FS::svc_Common, edit/part_svc.cgi from an installed web interface, export.html from the base documentation, FS::Record, FS::Conf, FS::cust_svc, FS::part_svc, FS::cust_pkg, FS::queue, freeside-queued), FS::svc_acct_pop, schema.html from the base documentation.

domain_select_hash %OPTIONS

Returns a hash SVCNUM => DOMAIN ... representing the domains this customer may at present purchase.

Currently available options are: pkgnum svcpart

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 2522:

'=item' outside of any '=over'