Difference between revisions of "Admin Module"

From BaseX Documentation
Jump to navigation Jump to search
(35 intermediate revisions by the same user not shown)
Line 1: Line 1:
This [[Module Library|XQuery Module]] contains functions for performing operations that are restricted to users with [[User Management|Admin Permissions]]. Existing users can be listed, and soon more.
+
This [[Module Library|XQuery Module]] contains functions for performing admin-centric operations such as managing database users and log data.
  
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://basex.org/modules/admin}} namespace, which is statically bound to the {{Code|admin}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/admin</nowiki></code> namespace, which is statically bound to the {{Code|admin}} prefix.<br/>
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
  
==admin:users==
+
==admin:sessions==
 
 
{{Mark|Updated with Version 7.8.2:}} md5-encoded password added to output.
 
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|admin:users||element(user)*}}<br/>{{Func|admin:users|$db as xs:string|element(user)*}}<br/>
+
|{{Func|admin:sessions||element(session)*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns an element sequence, containing all registered users along with their access permissions and md5-encoded passwords.<br/>If a database {{Code|$db}} is specified, users registered for a particular database will be returned.<br/>The output of this function is similar to the [[Commands#SHOW_USERS|SHOW USERS]] command.
+
|Returns an element sequence with all currently opened database sessions, including the user name, address (IP:port) and an optionally opened database.<br/>The output of this function and the {{Command|SHOW SESSIONS}} command is similar.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* {{Code|admin:users()}} returns <code><user permission="admin">admin</user></code> if no additional users have been created.
+
* {{Code|admin:sessions()}} may e.g. return <code><session user="admin" address="127.0.0.1:6286" database="factbook"/></code>
* {{Code|admin:users("factbook")}} returns all users that have been registered for the specified database.
 
 
|}
 
|}
  
==admin:sessions==
+
==admin:logs==
 +
 
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|admin:sessions||element(session)*}}
+
|{{Func|admin:logs||element(file)*}}<br/>{{Func|admin:logs|$date as xs:string|element(entry)*}}<br/>{{Func|admin:logs|$date as xs:string, $merge as xs:boolean|element(entry)*}}<br/>
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns an element sequence with all currently opened sessions, including the user name, address (IP:port) and an optionally opened database.<br/>The output of this function is similar to the [[Commands#SHOW_SESSIONS|SHOW SESSIONS]] command.
+
|Returns [[Logging]] data compiled by the database or HTTP server:
 +
* If no argument is specified, a list of all log files will be returned, including the file size and date.
 +
* If a {{Code|$date}} is specified, the contents of a single log file will be returned.
 +
* If {{Code|$merge}} is set to true, related log entries will be merged. Please note that the merge might not be 100% successful, as log entries may be ambiguous.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* {{Code|admin:sessions()}} may e.g. return <code><session user="admin" address="127.0.0.1:6286" database="factbook"/></code>
+
* {{Code|admin:logs()}} may return <code><file size="834367"/>2015-01-23</file></code> if a single log file exists.
 +
* {{Code|admin:logs() ! admin:logs(.)}} lists the contents of all log files.
 
|}
 
|}
  
==admin:logs==
+
==admin:write-log==
 +
 
 +
{{Mark|Updated with Version 9.2:}} Type string may contain more alphanumeric characters.
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|admin:write-log|$text as xs:string|empty-sequence()}}<br/>{{Func|admin:write-log|$text as xs:string, $type as xs:string|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Writes a string to the database logs, along with current user data (timestamp, user name). An optional log {{Code|$type}} can be specified. If omitted, the log type is {{Code|INFO}}.<br/>If the function is called from a database client, the IP will be logged. Otherwise, the string {{Code|SERVER}} will be logged.
 +
|-
 +
| '''Errors'''
 +
|{{Error|type|#Errors}} Type string contains whitespaces.
 +
|}
  
{{Mark|Updated with Version 7.8.2:}} represent name of log files as string value; {{Code|$merge}} argument added.
+
==admin:delete-logs==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|admin:logs||element(file)*}}<br/>{{Func|admin:logs|$date as xs:string|element(entry)*}}<br/>{{Func|admin:logs|$date as xs:string, $merge as xs:boolean|element(entry)*}}<br/>
+
|{{Func|admin:delete-logs|$date as xs:string|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns [[Logging]] data compiled by the database or HTTP server:
+
|Deletes the log entries from the specified <code>$date</code>
* If no argument is specified, a list of all log files will be returned, including the file size and date.
+
|-
* If a {{Code|$date}} is specified, the contents of a single log file will be returned.
+
| '''Errors'''
* If {{Code|$merge}} is set to true, related log entries will be merged. Please note that the merge might not be 100% successful, as log entries may be ambiguous.
+
|{{Error|today|#Errors}} Today's log file cannot be deleted.<br/>{{Error|delete|#Errors}} An error occurred while deleting a log file.
 +
|}
 +
 
 +
=Errors=
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="110"|Code
 +
|Description
 +
|-
 +
|{{Code|delete}}
 +
|An error occurred while deleting a log file.
 +
|-
 +
|{{Code|today}}
 +
|Today's log file cannot be deleted.
 
|-
 
|-
| '''Examples'''
+
|{{Code|type}}
|
+
|Type string contains whitespaces.
* {{Code|admin:logs()}} may return <code><file size="834367"/>2013-01-23</code> if a single log file exists.
 
* {{Code|for $log in admin:logs() return admin:logs($log)}} lists the contents of all log files.
 
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.2
 +
 +
* Updated: [[#admin:write-log|admin:write-log]]: type string may contain more characters
 +
 +
;Version 9.0
 +
 +
* Updated: error codes updated; errors now use the module namespace
 +
 +
;Version 8.3
 +
 +
* Updated: [[#admin:write-log|admin:write-log]]: optional log type added
 +
 +
;Version 8.2
 +
 +
* Added: [[#admin:delete-logs|admin:delete-logs]]
 +
 +
;Version 8.0
 +
 +
* Added: [[#admin:write-log|admin:write-log]]
 +
* Deleted: admin:users (renamed to [[User Module#user:list-details|user:list-details]])
  
 
;Version 7.8.2
 
;Version 7.8.2
Line 69: Line 116:
  
 
The Module was introduced with Version 7.5.
 
The Module was introduced with Version 7.5.
 
[[Category:XQuery]]
 

Revision as of 13:47, 16 April 2019

This XQuery Module contains functions for performing admin-centric operations such as managing database users and log data.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/admin namespace, which is statically bound to the admin prefix.

Functions

admin:sessions

Signatures admin:sessions() as element(session)*
Summary Returns an element sequence with all currently opened database sessions, including the user name, address (IP:port) and an optionally opened database.
The output of this function and the SHOW SESSIONS command is similar.
Examples
  • admin:sessions() may e.g. return <session user="admin" address="127.0.0.1:6286" database="factbook"/>

admin:logs

Signatures admin:logs() as element(file)*
admin:logs($date as xs:string) as element(entry)*
admin:logs($date as xs:string, $merge as xs:boolean) as element(entry)*
Summary Returns Logging data compiled by the database or HTTP server:
  • If no argument is specified, a list of all log files will be returned, including the file size and date.
  • If a $date is specified, the contents of a single log file will be returned.
  • If $merge is set to true, related log entries will be merged. Please note that the merge might not be 100% successful, as log entries may be ambiguous.
Examples
  • admin:logs() may return <file size="834367"/>2015-01-23</file> if a single log file exists.
  • admin:logs() ! admin:logs(.) lists the contents of all log files.

admin:write-log

Template:Mark Type string may contain more alphanumeric characters.

Signatures admin:write-log($text as xs:string) as empty-sequence()
admin:write-log($text as xs:string, $type as xs:string) as empty-sequence()
Summary Writes a string to the database logs, along with current user data (timestamp, user name). An optional log $type can be specified. If omitted, the log type is INFO.
If the function is called from a database client, the IP will be logged. Otherwise, the string SERVER will be logged.
Errors type: Type string contains whitespaces.

admin:delete-logs

Signatures admin:delete-logs($date as xs:string) as empty-sequence()
Summary Deletes the log entries from the specified $date
Errors today: Today's log file cannot be deleted.
delete: An error occurred while deleting a log file.

Errors

Code Description
delete An error occurred while deleting a log file.
today Today's log file cannot be deleted.
type Type string contains whitespaces.

Changelog

Version 9.2
Version 9.0
  • Updated: error codes updated; errors now use the module namespace
Version 8.3
Version 8.2
Version 8.0
Version 7.8.2
  • Updated: admin:users: md5-encoded password added to output.
  • Updated: admin:logs: represent name of log files as string value; $merge argument added.

The Module was introduced with Version 7.5.