Freeside:1.9:Documentation:Developer/FS/svc acct

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; _password_encoding - plain, crypt, ldap (or empty for autodetection); 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.
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 method 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.
radius_password: Returns a key/value pair containing the RADIUS attribute name and value for the password.
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, "{PLAIN}himom", "{CRYPT}94pAVyK/4oIBk" or "{MD5}5426824942db4253f87a1009fd5d2d4".

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)

POD ERRORS

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

Around line 440:: =cut found outside a pod block. Skipping to next block.
Around line 2626:: '=item' outside of any '=over'

Freeside:1.9:Documentation:Developer/FS/svc acct

Contents

NAME

SYNOPSIS

DESCRIPTION

METHODS

SUBROUTINES

BUGS

SEE ALSO

POD ERRORS

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools