jCIFS
Common Internet File System Client in 100% Java
http://jcifs.samba.org
The jCIFS SMB client library enables any Java application to remotely access shared files and directories on SMB file servers(i.e. a Microsoft Windows "share") in addition to domain, workgroup, and server enumeration of NetBIOS over TCP/IP networks. It is an advanced implementation of the CIFS protocol supporting Unicode, batching, multiplexing of threaded callers, encrypted authentication, transactions, the Remote Access Protocol (RAP), and much more. It is licensed under LGPL which means commercial organizations can legitimately use it with their proprietary code(you just can't sell or give away a modified binary only version of the library itself without reciprocation).
The API
The {@link jcifs.smb.SmbFile},
{@link jcifs.smb.SmbFileInputStream} , and {@link jcifs.smb.SmbFileOutputStream}
classes are analogous to the {@link java.io.File}, {@link java.io.FileInputStream}, and
{@link java.io.FileOutputStream} classes so if you know how to use those it
should be quite obvious how to use jCIFS provided you set any necessary
properties(such as a WINS server) and understand the smb://
URL syntax.
Here's an example to retrieve a file:
import jcifs.smb.*; jcifs.Config.setProperty( "wins", "192.168.1.220" ); SmbFileInputStream in = new SmbFileInputStream( "smb://username:password@host/c/My Documents/somefile.txt" ); byte[] b = new byte[8192]; int n; while(( n = in.read( b )) > 0 ) { System.out.write( b, 0, n ); }
You can also read/write, delete, make directories, rename, list contents of a directory, list the workgroups/ntdomains and servers on the network, list the shares of a server, open named pipes, authenticate web clients ...etc.
Setting Client Properties
It may be necessary to set various properties for the client to function properly. For example, to connect to a server on a remote subnet the IP address of a WINS server is required to retrieve the target address although DNS names and direct IP addresses are also valid server components within an SMB URL.
There are three ways to specify any of the available properties listed the table at the bottom of this page.
$ java -Djcifs.netbios.wins=192.168.1.220 MyApp
OR set a System property from within your application before any jCIFS classes are instantiated like:
System.setProperty( "wins", "192.168.1.220" );
jcifs.Config
class which is the class that maintains this information internally however, again, properties must be set before jCIFS client classes are referenced:
jcifs.Config.setProperty( "wins", "192.168.1.220" );
jcifs.util.PropertiesTree
file, all properties will be loaded from it. For example:
$ cat jcifs.prp wins=192.168.1.220 username=miallen password=legos56 ;baddr=192.168.1.255 ;log=ALL $ java -Djcifs.properties=jcifs.prp MyApp
Notice all jCIFS client properties have several dot '.' separated components whereas I have chosen only to specify the last label in the examples above. This is perfectly legal (except with -Dfull.property.name=value VM parameters). The following:
jcifs.netbios.wins jcifs.wins wins
are all identical. The more lengthy versions need only be used to avoid namespace conflicts. See the jcifs.util.PropertiesTree
class for more information.
Any properties specified using the -Djcifs.properties=myjcifsproperties.prp
file may be overridden using the System properties as will any -Dfull.property.name=value
VM parameters which in turn may then be overridden by the direct manipulation of properties using the Config
class.
Available Properties These properties may need to be specified for correct operation |
|
jcifs.smb.client.username | The default username used if not specified in an SMB URL |
jcifs.smb.client.password | The default password used if not specified in an SMB URL |
jcifs.smb.client.domain | The default authentication domain used if not specified in an SMB URL |
jcifs.netbios.wins | The IP address of the WINS server. This is only required when accessing hosts on different subnets although it is recomended if a WINS server is provided. |
jcifs.netbios.baddr |
The local network's broadcast address. It may be necessary to set this for certain network configurations because the default of 255.255.255.255 may otherwise throw a "Network is unreachable" IOException . For example if the local host's IP address is 192.168.1.15, the broadcast address would likely be 192.168.1.255.
|
jcifs.netbios.scope | This is extremely rare but NetBIOS provides for a "scope id" to be used in a attempt to conceal groups of machines on the same network. Ask your network administrator if scope id is used. If so, it must be set using this property or name queries will fail. |
jcifs.smb.client.laddr | The IP address of the local interface the client should bind to if it is different from the default. For example if the client is to be used over a dial-up connection the IP address of the PPP interface may need to be specified with this property. |
jcifs.netbios.laddr | The IP address of the local interface the client should bind to for name queries if it is different from the default. |
jcifs.netbios.lmhosts | The path to an lmhosts file containing a map of IP addresses to hostnames. The format of this file is identical to that of the Windows lmhosts file format. See Setting Name Resoultion Properties for details. |
jcifs.smb.client.disablePlainTextPasswords | Plain text passwords should never be used and are disabled by default. To enable jCIFS to use plain text password this property must be set to false. |
Less Commonly Used Properties These properties are not required for the client to function but may be necessary for optimal utility | |
jcifs.resolveOrder |
A comma separated list of name resolution method identifiers that specify which methods will be used and in what order to resolve hostnames. The possible identifiers in default order are LMHOSTS , WINS , BCAST , and DNS .
See Setting Name Resoultion Properties for details.
|
jcifs.netbios.resolveOrder | Removed This property has been renamed to the above jcifs.resolveOrder. It is no longer specific to the NetBIOS package. |
jcifs.util.log |
A series of string identifiers to induce log messages to be printed to the console such as log=EXC,DEB,WAR,HEX would log internal exceptions, debugging, warnings, and hex dumps of network packets. ALL may be specified to indicate all messages should be logged. The ALL argument will produce more messages than EXC,DEB,WAR,HEX combined. NON will not print anything to the console including exceptions.
|
jcifs.smb.client.attrExpirationPeriod |
Attributes of a file are cached for attrExpirationPeriod milliseconds. The default is 5000. This greatly improves performance because it eliminates redundant calls to the server however it is possible that two separate instances of SmbFile s pointing to the same resource may produce different results in awkward situations (e.g. s1.canRead() may return true even though s2.delete() was called immediately before). For maximum reliability, turn off attribute expiration by setting this property to 0.
|
jcifs.smb.client.responseTimeout | The time period in milliseconds that the client will wait for a response to a request from the server. The default value is 10000. Under poor network conditions you may wish to increase this value but jcifs.smb.client.soTimeout should be increased as well to accommodate. |
jcifs.smb.client.soTimeout | To prevent the client from holding server resources unnecessarily, sockets are closed after this time period if there is no activity. This time is specified in milliseconds. The default is 15000. |
jcifs.netbios.cachePolicy | When a NetBIOS name is resolved with the NbtAddress class it is cached to reduce redundant name queries. This property controls how long, in seconds, these names are cached. The default is 30 seconds, 0 is no caching, and -1 is forever. |
jcifs.netbios.hostname |
In the course of standard operations the client must present a NetBIOS name to servers. A name is dynamically generated(e.g. JCIFS35_177_E6 ) for this purpose however it may be desirable to set this property to a specific name(e.g. PROD_FEED3 ) for reasons such as server accounting purposes.
|
jcifs.smb.client.listSize |
One command that may be individually tuned is the TRANS2_FIND_FIRST/NEXT2 operation. It is provoked by the list() method of SmbFile (but not for smb:// , smb://workgroup/ , or smb://server/ URLs). The size of the data buffer used, in bytes, can be set with this property. The default size is 1200 bytes.
|
jcifs.smb.client.listCount |
Similar to listSize property above, listCount is for tuning the TRANS2_FIND_FIRST/NEXT2 operation. It controls the maximum number of directory and file entries that should be returned with each request. The default is 15.
|
jcifs.smb.client.lport | If a particular local port must be used for socket communications, perhaps because a firewall requires the source port to be a specific value, it can be set with this property(e.g. lport=5139). This has no effect on the remote port which is invariably 139. |
jcifs.netbios.soTimeout | To prevent the client from holding resources unnecessarily, the datagram socket used for nameservice queries is closed after this time period which is specified in milliseconds. The default is 5000. |
jcifs.netbios.lport | If a particular local port must be used for socket communications, perhaps because a firewall requires the source port to be a specific value, it can be set with this property(e.g. lport=5137). This has no effect on the remote port which is invariably 137. |
jcifs.netbios.retryCount | The number of times a name query should be attempted if no answer is received. In adverse network conditions one may wish to increase this value however failed name queries take retryCount * retryDuration milliseconds. The default value is 2. Should probably increase jcifs.netbios.retryTimeout instead. |
jcifs.netbios.retryTimeout | The duration in milliseconds that the client will wait for a response to a name query. The default is 3000. |
jcifs.http.domainController | The IP address of a server that should be used to authenticate HTTP clients with the NtlmSsp class (use by NtlmHttpFilter and NetworkExplorer). If this is not specified the jcifs.smb.client.domain 0x1C NetBIOS group name will be queried. It is not necessary for this to specify a real domain controller. The IP address of a workstation will do for development purposes. We do not support DCE/RPC NETLOGON. See jCIFS NTLM HTTP Authentication and the Network Explorer Servlet for more information. |
jcifs.smb.client.codepage | Removed See jcifs.encoding property below. |
jcifs.encoding | The character encoding the client should use to decode and encode 8 bit strings. This refers to the target server's character set (e.g. encoding=Cp866 for Russian). See this list of Supported Encodings. |
jcifs.http.basicRelm | The realm for basic authentication. This property defaults to 'jCIFS'. |
jcifs.http.enableBasic |
![]() |
jcifs.http.insecureBasic |
![]() |
jcifs.smb.lmCompatibility |
![]()
|
jcifs.smb.client.ssnLimit |
![]() |
jcifs.smb.client.signingPreferred |
![]() |
jcifs.http.loadBalance |
![]() |
jcifs.netbios.lookupRespLimit |
![]() |
Advanced Properties These should not be changed | |
jcifs.smb.client.nativeOs | Specifies the NativeOS field in the SMB_COM_SESSION_SETUP_ANDX command. The default is the os.name system property. |
jcifs.smb.client.nativeLanMan | Specifies the NativeLanMan field in the SMB_COM_SESSION_SETUP_ANDX request. The default is "jCIFS". |
jcifs.smb.client.maxMpxCount | This client can send and receive messages concurrently over the same socket. The number of simultaneous outstanding transactions with a given server is controlled by this property. The default is 10. Under extremely unlikely circumstances this value may need to be adjusted to achive optimal throughput. It is more likely this property would be set to 1 to support a deficient server. |
jcifs.smb.client.useNTSmbs | This property is largely ignored. |
jcifs.smb.client.useUnicode | This client will use Unicode strings wherever negotiated. Setting this property to false will remove Unicode capability and therefore use only 8 bit strings will used (although Unicode will still be used to accomodate a few protocol bugs). |
jcifs.netbios.client.writeSize | The size of buffer in bytes that the NetBIOS Socket layer uses to write data to the raw socket. The default is 1500 and in effect limits the NetBIOS session service outbound message size. |
jcifs.smb.client.flags2 | A carefully crafted integer may be used with this property to specify the flags2 field of the SMB header. |
jcifs.smb.client.capabilities | A carefully crafted integer may be used with this property to specify the capabilities field of the SMB_COM_SESSION_SETUP_ANDX command. |
jcifs.smb.client.rcv_buf_size | One buffer is used to decode incoming packets. The size of this buffer may be specified, in bytes, using this property. The default is 60416. |
jcifs.smb.client.serviceType | The service type should always be '?????' which means that the server should resolve it and to my knowledge this resolution mechanism has never failed. But ... should one wish to experiment you can set it with this property. Service types can be at least A:, LPT1:, IPC, and COMM. |
jcifs.smb.client.<smb_ident>.<smb_ident> | It is possible to "tune" batching (a.k.a chaining) by specifying and integer batch level for a pair of SMB messages. See Batching for details. |
jcifs.smb.client.useBatching |
To turn off batching altogether specify false for this property. The default is true .
|
jcifs.smb.client.tcpNoDelay |
If this property is true , the socket that jCIFS uses will wait for a fraction of a second to collect several messages for more efficient transmission in one packet. This sets the setTcpNoDelay for the NetBIOS socket to true. By default Java sockets and the jCIFS client do not delay; the default value is false .
|