Freeside:3: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; slipip: IP address
seconds; upbytes; downbyte; totalbytes; domsvc: svcnum from svc_domain
pbxsvc: Optional svcnum from svc_pbx
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.
set_password: Set the cleartext password for the account. If _password_encoding is set, the new password will be encoded according to the existing method (including encryption mode, if it can be determined). Otherwise, config('default-password-encoding') is used.

If no password is supplied (or a zero-length password when minimum password length is >0), one will be generated randomly.
_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.
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.
cgp_rpop_hashref: Returns an arrayref of RPOP data suitable for Communigate Pro API commands.
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.
last_login_text: Returns text describing the time of last login.
psearch_cdrs OPTIONS: Returns a paged search (FS::PagedSearch) for Call Detail Records associated with this service. For svc_acct, "associated with" means that either the "src" or the "charged_party" field of the CDR matches the "username" field of the service.
get_cdrs (DEPRECATED): Like psearch_cdrs, but returns all the FS::cdr objects at once, in a single list. Arguments are the same as for psearch_cdrs.
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/

CLASS METHODS

search HASHREF

Class method which returns a qsearch hash expression to search for parameters specified in HASHREF. Valid parameters are

domain: ; domsvc:; unlinked:; agentnum:; pkgpart; Arrayref of pkgparts
pkgpart: ; where; Arrayref of additional WHERE clauses, will be ANDed together.
order_by: ; cust_fields

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; 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.

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

_op_usage and set_usage bypass the history... maybe they shouldn't

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

Contents

NAME

SYNOPSIS

DESCRIPTION

METHODS

CLASS METHODS

SUBROUTINES

BUGS

SEE ALSO

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools